@zudojs/openapi

OVERVIEW

An OpenAPI document is a machine-readable description of an HTTP API. It lists every path, every method, what you send, and what comes back. It is normally written as one JSON or YAML file.

Because it is machine-readable, tools can read it and do work for you: render browsable documentation, generate a client library in another language, produce request collections, or check in CI that your API has not changed by accident.

Writing that file by hand goes stale the moment code changes. @zudojs/openapi builds it from the route metadata and schemas you already have, so the description and the code move together.

INSTALLATION

The runtime dependencies are @zudojs/errors (v1.3.0) and @zudojs/constants (v1.1.2), which supplies the schema ceilings the converter emits. Install @zudojs/schema too if you want to register schemas rather than hand-written OpenAPI objects:

Schemas are read structurally, not imported, so any object with the same runtime shape works.

QUICK START

OpenAPIManager is the one class most applications use. You give it document metadata, add routes, then ask for the document.

Three things happened without you asking:

• → /orders/:id became the OpenAPI path template /orders/{id}.
• → The id parameter was marked required: true, because OpenAPI requires that of every path parameter.
• → The document got a info["x-logo"] entry so viewers show a logo. See Branding.

DESCRIBING ROUTES

A route here is a method, a path, and some metadata. The metadata lives under metadata.openapi and holds the fields OpenAPI calls an operation: what this endpoint is called, what it takes, and what it returns.

Every field is optional. The main ones:

This adds a second route with a body and a tag, then prints the methods that ended up on the path:

Use addRoute for a route you are adding once; it throws if the same route is already registered. Use setRoute when replacing is what you want, and removeRoute(method, path) to drop one.

Since v1.4.0 “the same route” means the same method and the same OpenAPI path template, not the same source string. GET /users/:id and GET /users/{id} both become the path item /users/{id}, so the second one is now rejected with an OpenAPIRouteError. Before v1.4.0 both registered and generation silently kept only the last one: an operation disappeared from the published document and validate() reported nothing wrong. hasRoute, setRoute and removeRoute accept either spelling for the same route.

Routes with no documented responses

OpenAPI requires every operation to list at least one response. If a route declares none (no responses field, or responses: {}), the generator does not make one up. It emits a default response described as "Undocumented response", which keeps the document valid while saying honestly that nothing is known, and it reports a warning so you can fix the route:

Before v1.5.0 such a route got an invented "200": { description: "OK" }. That was a guess, and often a wrong one: a DELETE that answers 204 No Content was published as returning 200, so a client generated from the document expected a body that never came. The guess also hid the problem, because the validator's “every operation declares a response” check could never fire.

The warning reaches three places: the onRouteWarning(message) option (accepted by new OpenAPIManager, createOpenAPIDocumentFromRoutes and createOpenAPIManagerFromRoutes), onSchemaWarning under the name "routes", and manager.routeWarnings(). @zudojs/http's generateOpenAPIDocument passes its own onRouteWarning through, so these arrive next to its duplicate-route warnings.

GENERATING FROM A ROUTE TABLE

Most of the time you do not want to call addRoute once per endpoint. Your routes already exist somewhere — in a router, or in a list of operations — and the document should come from that list, so it can never describe an endpoint that is not there.

createOpenAPIDocumentFromRoutes(routes, { info }) does that. routes is a plain array of route descriptors: one object per endpoint, holding its method, its path, and the same documentation fields as metadata.openapi, all flattened into one object. Schemas can be @zudojs/schema schemas, which are converted for you.

What happened: /users/:id became /users/{id} with a required id parameter, the body schema became a required application/json request body, the 404 kept its description, and the 200 and 201 got theirs from the reason phrase. validate: true throws an OpenAPIValidationError if the result is invalid.

The route descriptor

An OpenAPIRouteDescriptor is RouteOpenAPIMetadata plus method and path. Only those two are required.

Every path template slot is documented as a required string parameter even when nothing declares it. A declared path parameter the template does not contain is dropped with a warning, rather than producing an invalid document. Warnings reach onRouteWarning, onSchemaWarning under the name "routes", and manager.routeWarnings(). A route with no responses warns too (see Routes with no documented responses).

Where descriptors come from

• → @zudojs/http builds them from a router's registered routes: generateOpenAPIDocument(router, { info }) and mountOpenAPI(router, { info }) call this function for you.
• → @zudojs/api builds them from operations: toOpenAPIRouteDescriptors(registry, { basePath }).
• → Or write the array yourself, as above.

Keeping a manager instead

createOpenAPIManagerFromRoutes(routes, options) takes the same arguments but returns the OpenAPIManager, so you can serve it with toResponse() and toUIResponse(). When your routes change, manager.setRoutes(routes.map(routeDescriptorToRouteInfo)) replaces the whole route set at once, rejecting duplicates before anything changes. routeDescriptorToRouteInfo converts one descriptor into the { method, path, metadata } shape addRoute takes.

SCHEMAS

A schema describes the shape of a value: which fields exist, their types, and what counts as valid. OpenAPI has its own schema dialect, and addSchema translates a @zudojs/schema schema into it.

Registering a schema puts it in components.schemas under the name you give, so operations can point at it with a $ref instead of repeating it.

optional, default, any and unknown fields are left out of required, matching what the runtime accepts; constraints on coerced schemas and factory defaults are carried into the document. A string or array with no explicit maximum gets the limit the runtime enforces (maxLength: 255 / maxItems: 1000), read from @zudojs/constants SCHEMA_DEFAULT_MAX_STRING_LENGTH / SCHEMA_DEFAULT_MAX_ARRAY_LENGTH.

Point an operation at it with createComponentReference, which builds the $ref string and escapes names containing / or ~:

Unknown keys

An object schema decides what happens to a key it does not declare: .strip() (the default) discards it and accepts the payload, .passthrough() keeps it, and .strict() rejects the payload. Only .strict() emits additionalProperties: false, because that keyword is OpenAPI for “reject the payload”.

Before v1.4.0 a stripping object emitted additionalProperties: false too. A client generated from that document refused requests the service would have accepted — it declared the extra key fatal while the parser was quietly dropping it. It also made objectSchema({…}) and objectSchema({…}).strip() document differently despite validating identically. Both now produce the same schema.

When a constraint cannot be expressed

Some things your schema can say have no OpenAPI equivalent. Rather than emit an empty {} and let you find out in production, the converter records a warning and still emits everything it can.

OpenAPI's pattern keyword carries the regular expression source and nothing else — there is no place to put i or m. A case-insensitive pattern would therefore become case-sensitive in the published document, which is stricter than the code that actually validates requests. The converter no longer lets that pass unremarked: the flags show up in a warning naming the pattern.

Warnings from a schema you registered are collected per component:

Already have an OpenAPI schema object, hand-written or from somewhere else? Register it as-is with addRawSchema(name, schema), which skips conversion.

3.0 VS 3.1

OpenAPI 3.0 and 3.1 spell several schema keywords differently. Emitting the 3.1 spelling into a 3.0 document does not fail loudly — a strict tool rejects the whole file and a lenient one drops the keyword, so the constraint is simply gone.

The converter takes the target version from the manager and emits the spelling that version defines. You choose the version once, in the constructor.

In 3.1, exclusiveMinimum holds the number. In 3.0 it is a boolean that modifies minimum. Both spellings now come out right:

VALIDATION

A document can be well-formed JSON and still be a broken OpenAPI file. The validator reads a finished document and reports what is wrong before a tool downstream trips over it.

validate() reports; it never throws:

Two operations share the operationId "orders.get", so a code generator would produce two methods with the same name. Rename the second one (say, "orders.list") and it passes.

What it checks

• → Required document fields are present and openapi names a supported version.
• → Every operation declares at least one response, keyed by a status code, a 4XX-style range or default, each with a description. Generated documents always pass this one (an undocumented route gets default and a warning), so it matters most for documents built by hand.
• → Path templates and in: "path" parameters agree in both directions, path parameters are required, no parameter is declared twice in one list (an operation-level parameter may override a path-level one), and no two paths are identical apart from their template parameter names.
• → operationId values are unique and within MAX_OPERATION_ID_LENGTH.
• → Every security requirement names a scheme declared in components.securitySchemes, and every declared scheme is used somewhere.
• → Every local $ref resolves inside the document, and every non-local one uses an allowed scheme.
• → No path still uses :id instead of {id}.

Where a $ref may point

A $ref is an instruction to whatever reads the document: go fetch this and paste it here. Most refs are local — #/components/schemas/Order — and the validator checks they resolve.

A ref that is not local is checked for its URI scheme. Only http and https are allowed. Anything else is an error.

An https or relative ref is legal OpenAPI, so it is a warning, not an error: the document stays valid, but you are told something outside it will be fetched. Bundle the target into components if the source is not fully trusted.

Failing loudly

Pass true to generate, toJSON or toYAML and an invalid document throws instead. The error carries the issues:

SERVING THE DOCS

Two endpoints are all you need. One serves the specification, the other serves a page that reads it.

• → toResponse() — the document itself, as JSON or YAML.
• → toUIResponse({ specUrl }) — a complete HTML documentation page that fetches the spec from specUrl.

Both return the same plain shape — { status, headers, body } — so any HTTP adapter can turn them into its own response type.

Wired into an HTTP framework, that is two handlers:

On @zudojs/http you do not write these two handlers: mountOpenAPI(router, { info }) registers both, generated from the router's own routes.

Open /docs and you get a browsable page: every endpoint listed by tag, expandable request and response shapes, and a "try it out" button that sends a real request.

Swagger UI or ReDoc

Swagger UI is the default: interactive, good for poking at an API by hand. ReDoc renders a three-column reference document — better for reading, no try-it-out. Choose with renderer.

You can also render the page on its own, without a manager, with renderOpenAPIUI. It returns the HTML string; serve it with content-type: text/html.

Air-gapped deployments

By default the page loads exact, pinned versions of Swagger UI or ReDoc from cdn.jsdelivr.net with Subresource Integrity, and toUIResponse sends a restrictive content-security-policy header (pass contentSecurityPolicy: false to omit it). A machine with no internet access renders a blank page. Host the viewer's files yourself and point assetsBaseUrl at them:

For ReDoc the file needed under that base is redoc.standalone.js.

BRANDING

ReDoc, Scalar and several other viewers look for a logo in a non-standard info["x-logo"] field. Generated documents carry one by default, so a spec opened in any of those tools shows a logo instead of nothing.

The branding option controls it. There are three ways to use it:

A logo you put on info yourself is never overwritten — set info["x-logo"] directly and that is what the document carries, whatever branding says.

The brand assets are exported too, as inline SVG strings and as data URIs, so a page can use them with no extra network request:

The full set: ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, and a _DATA_URI counterpart for each.

BUILDING BY HAND

If you are not generating from routes — describing an API you did not write, or assembling a document in a script — use OpenAPIDocumentBuilder. Every method returns the builder, so calls chain, and build() returns the finished document.

The builder and the manager assemble documents through the same registry, so both produce the same shape and obey the same rules.

Serialize any document with toOpenAPIJSON or toOpenAPIYAML. The YAML is real YAML: strings that YAML would otherwise reinterpret — true, null, 1.0, anything starting with a reserved character — come out quoted.

API REFERENCE

Classes

OpenAPIManager methods

Functions

Types

Errors

All extend OpenAPIError, the @zudojs/errors class re-exported here (a BaseError). They default to status 500 and are not exposed to clients — these are failures while your service builds its own specification, not answers to a request.

Constants

COMMON MISTAKES

• Leaving out the responses.
  A route with no responses is published with a default “Undocumented response”, and every generated client has to guess what comes back. Declare the real ones, such as "204" for a delete, and listen to onRouteWarning so a new undocumented route shows up in your logs.
• Serving the spec but not a page, or a page but not the spec.
  A toUIResponse page fetches specUrl at load time and shows an error if nothing answers. Register both handlers, and make specUrl match the route the spec is actually on.
• Assuming a 3.1 document still means the same thing as 3.0.
  Copying a document between versions silently drops exclusive bounds and nullability. Set version on the manager and let the converter emit the right spelling.
• Ignoring schema warnings.
  A dropped constraint — an unknown string format, a regex flag OpenAPI cannot express — is not an error, so nothing stops the build. Pass onSchemaWarning or read schemaWarnings() and log them.
• Pasting a $ref from an untrusted document.
  A non-http(s) ref is now an error, but an https one is only a warning — legal OpenAPI, and still a fetch your resolver will perform. Bundle the target into components when the source is not yours.
• Calling the deprecated invalidate() expecting a cache drop.
  It clears every registered route as well. Use invalidateCache() for the cache, reset() when you really mean to empty the manager.

RELATED

• @zudojs/schema — defines the schemas addSchema converts. Start here if you have no schemas yet.
• @zudojs/http — generateOpenAPIDocument(router) and mountOpenAPI(router) document a router's own routes with this package.
• @zudojs/api — toOpenAPIRouteDescriptors(registry) turns operations into route descriptors.
• @zudojs/errors — the BaseError every OpenAPI error extends.
• @zudojs/validation — checks incoming requests at runtime, which OpenAPI only describes.

COMPLETE EXPORT INDEX

Every name @zudojs/openapi exports from its package root at v1.5.0 — 138 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.