Openapi

OpenAPI 3.1 / 3.2 emitter from declarative route declarations + schemas (composable with b.safeSchema); JSON / YAML output. Operators describe their public HTTP surface as an OpenAPI document the framework serves at /openapi.json (or any path) for downstream tooling: API consumers, Postman, code-generators, contract-test rigs.

The builder is FRAMEWORK-FACING: it produces a valid OpenAPI document, but the operator's hand-written contract is the source of truth — it does NOT auto-walk b.router routes (operators frequently want a smaller / different surface published than what the router exposes internally).

3.1.0 is the default emitted version. Pass create({ openapi: "3.2.0", ... }) to opt into OpenAPI 3.2; both 3.1.x and 3.2.x parse and emit. The 3.2 additions wired here are the top-level webhooks map (named out-of-band Path Item Objects the API initiates — OpenAPI 3.2 §4.8.2) and the jsonSchemaDialect field (declares the default JSON Schema dialect for the document — OpenAPI 3.2 §4.8.1).

The builder fluent surface is path() / webhook() / schema() / response() / parameter() / requestBody() / header() / example() / security.add() / security.require() / tag() / server(), each returning the builder for chaining. Terminal calls are toJson() (JSON document with referential integrity checked — every security-scheme reference must resolve), toJsonString(), toYaml(), and middleware(opts) which mounts the cached document at request-time. Security-scheme builders for bearer / basic / apiKey / oauth2 / openIdConnect / mtls / dpop live on b.openapi.security.

b.openapi.create(opts) #

{
  info:              { title, version, description?, contact?, license? },   // REQUIRED — title + version are non-empty strings
  openapi:           string,        // emitted version — "3.1.x" (default) or "3.2.x"
  jsonSchemaDialect: string,        // default JSON Schema dialect URI for the document
  servers:           array,         // [{ url, description?, variables? }, ...]
  externalDocs:      { url, description? },
  tags:              array,         // [{ name, description? }, ...] — seed; builder.tag() appends more
  security:          array,         // doc-level security requirements [{ schemeName: ["scope"] }, ...]
}

Build a fluent OpenAPI 3.1 / 3.2 document builder. opts.info is required (title + version). Returns a chainable builder; terminal calls are toJson(), toJsonString(indent), toYaml(), and middleware(opts). toJson() cross-checks every doc-level and per-operation security requirement against components.securitySchemes and throws OpenApiError("openapi/dangling-security") on a missing scheme.

3.1.0 is emitted by default. Pass openapi: "3.2.0" to opt into OpenAPI 3.2; an unsupported version (e.g. "4.0.0") throws OpenApiError("openapi/bad-version"). webhook(name, method, opts) registers a top-level webhook (OpenAPI 3.2 §4.8.2) and jsonSchemaDialect declares the document's default JSON Schema dialect (OpenAPI 3.2 §4.8.1) — both valid in 3.1.x and 3.2.x.

var doc = b.openapi.create({
  openapi: "3.2.0",
  info:    { title: "Acme API", version: "1.0.0" },
  servers: [{ url: "https://api.acme.example.com" }],
});
doc.security.add("bearerAuth", b.openapi.security.bearer({ bearerFormat: "JWT" }));
doc.path("get", "/users/{id}", {
  summary:    "Fetch a user",
  parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
  responses:  { "200": { description: "ok" }, "404": { description: "not found" } },
  security:   [{ bearerAuth: [] }],
});
doc.webhook("newPet", "post", {
  requestBody: { content: { "application/json": { schema: { type: "object" } } } },
  responses:   { "200": { description: "ack" } },
});
var json = doc.toJson();
json.openapi;           // → "3.2.0"
json.webhooks.newPet.post.responses["200"].description;   // → "ack"

b.openapi.parse(jsonStringOrObject) #

Parse + validate an external OpenAPI 3.1 / 3.2 document. Operators hand a doc that arrived from a downstream integration (consumer hand- edited, contract-test fixture, third-party publish) and want the framework's gate to enforce the same shape rules toJson() enforces on builder output. Throws on invalid JSON or non-object input; otherwise returns { doc, errors, valid }. errors is an array of strings — empty on a valid document. The openapi version must be 3.1.x or 3.2.x. Path keys must start with /, every operation must declare responses with a description, path parameters must carry required: true, and doc-level security must reference declared schemes. Top-level webhooks (OpenAPI 3.2 §4.8.2) are validated with the same operation rules but free-form names instead of /-prefixed URL keys; jsonSchemaDialect (OpenAPI 3.2 §4.8.1) must be a string when present.

var result = b.openapi.parse('{"openapi":"3.2.0","info":{"title":"x","version":"1.0.0"}}');
result.valid;       // → true
result.errors;      // → []

var bad = b.openapi.parse({ openapi: "3.1.0", info: { title: "x", version: "1.0.0" }, paths: { "users": {} } });
bad.valid;          // → false
bad.errors[0];      // → 'path "users" must start with \'/\''

Last updated 2026-08-08T16:39:49.652Z by seeder.