nori - v1.0.0

nori

OpenAPI library for Gleam.

A comprehensive OpenAPI 3.1.x library providing:

Quick Start

Parsing an OpenAPI document

import nori

pub fn main() {
  let json = "{\"openapi\": \"3.1.0\", \"info\": {\"title\": \"My API\", \"version\": \"1.0.0\"}}"
  let assert Ok(doc) = nori.parse_json(json)
  io.println("API: " <> doc.info.title)
}

Building an OpenAPI document

import nori
import nori/document
import nori/paths
import nori/operation
import nori/server

pub fn main() {
  let doc =
    document.v3_1_0("My API", "1.0.0")
    |> document.add_server(server.new("https://api.example.com"))
    |> document.add_path("/users", paths.get(operation.with_id("listUsers")))

  let json = nori.to_json(doc)
}

Types

ParseError

</>

Error types for parsing OpenAPI documents.

pub type ParseError {
  JsonParseError(message: String)
  DecodeError(errors: List(decode.DecodeError))
  UnsupportedVersion(version: String)
}

Constructors 

  • JsonParseError(message: String)

    JSON parsing failed

  • DecodeError(errors: List(decode.DecodeError))

    Document decoding failed

  • UnsupportedVersion(version: String)

    Unsupported OpenAPI version

Values

api_version

</> 
pub fn api_version(doc: document.Document) -> String

Gets the version from an OpenAPI document’s info.

build_ir

</> 
pub fn build_ir(doc: document.Document) -> ir.CodegenIR

Build a language-agnostic codegen intermediate representation from a parsed document.

CodegenIR is the contract between the parser and any code generator (built-in Gleam/TypeScript, or third-party satellite packages). Walk it directly to drive your own emitters.

Examples

let assert Ok(doc) = nori.parse_file("api.yaml")
let codegen_ir = nori.build_ir(doc)
// pass codegen_ir to your own generator

check_capabilities

</> 
pub fn check_capabilities(
  doc: document.Document,
) -> Result(document.Document, List(capability.Issue))

Walk a parsed document and collect any OpenAPI features nori does not yet support. Returns the document unchanged when nothing is flagged, otherwise a list of Issues sorted with blocking severity first.

Use this before build_ir if you want to fail fast instead of producing degraded codegen output.

Examples

let assert Ok(doc) = nori.parse_file("api.yaml")
case nori.check_capabilities(doc) {
  Ok(_) -> generate(doc)
  Error(issues) -> {
    list.each(issues, fn(i) { io.println(capability.issue_to_string(i)) })
  }
}

parse

</> 
pub fn parse(
  input: String,
) -> Result(document.Document, ParseError)

Alias for parse_json.

parse_file

</> 
pub fn parse_file(
  path: String,
) -> Result(document.Document, ParseError)

Loads and parses an OpenAPI spec file (YAML or JSON).

Detects format by file extension (.yaml/.yml → YAML, .json → JSON).

Examples

let assert Ok(doc) = nori.parse_file("./nori.yaml")

parse_json

</> 
pub fn parse_json(
  input: String,
) -> Result(document.Document, ParseError)

Parses an OpenAPI document from a JSON string.

Examples

let json = "{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"My API\", \"version\": \"1.0.0\" } }"
let assert Ok(doc) = nori.parse_json(json)

parse_yaml

</> 
pub fn parse_yaml(
  input: String,
) -> Result(document.Document, ParseError)

Parses an OpenAPI document from a YAML string.

Examples

let yaml = "openapi: '3.1.0'\ninfo:\n  title: My API\n  version: '1.0.0'"
let assert Ok(doc) = nori.parse_yaml(yaml)

spec_version

</> 
pub fn spec_version(doc: document.Document) -> String

Gets the OpenAPI specification version as a string.

title

</> 
pub fn title(doc: document.Document) -> String

Gets the title from an OpenAPI document.

to_json

</> 
pub fn to_json(doc: document.Document) -> String

Serializes an OpenAPI document to a JSON string.

Examples

let json = nori.to_json(doc)

to_json_pretty

</> 
pub fn to_json_pretty(doc: document.Document) -> String

Serializes an OpenAPI document to a pretty-printed JSON string.

Examples

let json = nori.to_json_pretty(doc)
✨ Search Document