@zudojs/openapi 0.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/openapi
 
-OpenAPI 3.1 specification generation, validation, and SDK generation for Zudojs applications.
+OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.
 
 ## Installation
 
@@ -10,35 +10,354 @@ npm install @zudojs/openapi
 
 ## Quick Start
 
+`OpenAPIManager` coordinates route collection, schema conversion, document
+assembly, validation and serving.
+
 ```typescript
-import { createOpenAPIRouter } from "@zudojs/openapi";
+import { OpenAPIManager } from "@zudojs/openapi";
 
-const router = createOpenAPIRouter({
-  info: { title: "My API", version: "1.0.0" },
+const manager = new OpenAPIManager({
+  version: "3.1.0",
+  info: { title: "Orders API", version: "1.2.0" },
+  servers: [{ url: "https://api.example.com" }],
 });
 
-router.get(
-  "/users/:id",
-  {
-    responses: { 200: { schema: UserSchema } },
-  },
-  async (ctx) => {
-    return ctx.params.id;
+manager.addRoute({
+  method: "get",
+  path: "/users/:id",
+  metadata: {
+    openapi: {
+      operationId: "users.get",
+      summary: "Get a user",
+      tags: ["users"],
+      parameters: [{ name: "id", in: "path", schema: { type: "string" } }],
+      responses: {
+        "200": { description: "User found" },
+        "404": { description: "No such user" },
+      },
+    },
   },
+});
+
+const document = manager.generate(true); // true = validate while generating
+const json = manager.toJSON();
+const yaml = manager.toYAML();
+```
+
+Every documented response reaches the document — `4xx`, `5xx` and `default`
+included. `:id` becomes `{id}`, and a path parameter is marked required
+because the specification requires it.
+
+Generation is idempotent: call `generate()` as often as you like.
+
+## Serving the document
+
+```typescript
+const response = manager.toResponse({ format: "json" });
+// { status: 200, headers: { "content-type", "cache-control" }, body }
+```
+
+`{ status, headers, body }` is framework-agnostic; hand it to whichever HTTP
+adapter you use.
+
+## Serving a documentation page
+
+`toUIResponse` returns the same `{ status, headers, body }` shape carrying a
+complete HTML page that reads the specification from `specUrl`. Pair it with
+`toResponse`, which serves the specification itself:
+
+```typescript
+app.get("/openapi.json", () => manager.toResponse());
+app.get("/docs", () => manager.toUIResponse({ specUrl: "/openapi.json" }));
+```
+
+Swagger UI is rendered by default; pass `renderer: "redoc"` for ReDoc.
+
+```typescript
+manager.toUIResponse({ specUrl: "/openapi.json", renderer: "redoc" });
+```
+
+`renderOpenAPIUI(options)` returns the HTML string on its own, without a
+manager. Both accept the same options:
+
+| Option           | Meaning                                            | Default            |
+| ---------------- | -------------------------------------------------- | ------------------ |
+| `specUrl`        | Where the page fetches the document from (required) | —                  |
+| `title`          | Page title and header text                          | `"API reference"`  |
+| `renderer`       | `"swagger"` or `"redoc"`                            | `"swagger"`        |
+| `logo`           | Header logo, or `false` for none                    | Zudo wordmark      |
+| `favicon`        | Favicon URL or data URI, or `false`                 | Zudo favicon       |
+| `customCss`      | CSS appended after the built-in theme               | —                  |
+| `assetsBaseUrl`  | Where the viewer's own JS and CSS load from         | public CDN         |
+| `swaggerOptions` | Forwarded to `SwaggerUIBundle`; ignored by ReDoc    | —                  |
+
+`assetsBaseUrl` points the viewer's assets at a self-hosted copy, which is what
+an air-gapped deployment needs — the default CDN renders a blank page with no
+egress. Swagger UI loads `swagger-ui.css` and `swagger-ui-bundle.js` from that
+base; ReDoc loads `redoc.standalone.js`.
+
+```typescript
+manager.toUIResponse({ specUrl: "/openapi.json", assetsBaseUrl: "/vendor/swagger" });
+```
+
+Caller-supplied text is escaped, and input that would break out of the page is
+refused rather than mangled: a `javascript:` or `vbscript:` URL throws (the
+scheme is read after stripping the control characters browsers ignore, so
+`java\nscript:` is caught too), a `data:` URL that is not an image throws
+(the assets base lands in `<script src>`), an empty `specUrl` throws, and
+`customCss` containing `</style>` throws — that sequence ends the style block
+and lets the rest be parsed as HTML.
+
+## Branding
+
+ReDoc, Scalar and several other viewers read a logo from the non-standard
+`info["x-logo"]` field. Generated documents carry the Zudo mark there by
+default, so a spec opened in one of them shows a logo rather than nothing.
+
+```typescript
+new OpenAPIManager({ info }).generate().info["x-logo"];
+// { url: "data:image/svg+xml;…", href: "https://zudo.dev", altText: "Zudo", … }
+```
+
+The `branding` option controls it, and the same value is used by
+`toUIResponse` for the page header:
+
+- omitted or `true` — the Zudo mark
+- `false` — no `x-logo`, and no logo on the page
+- an `OpenAPILogo` (`{ url, href?, altText?, backgroundColor? }`) — your own
+
+```typescript
+new OpenAPIManager({ info, branding: false });
+new OpenAPIManager({
+  info,
+  branding: { url: "https://acme.example/logo.svg", href: "https://acme.example", altText: "Acme" },
+});
+```
+
+A logo already present on `info["x-logo"]` is never overwritten, whatever
+`branding` says.
+
+The brand assets are exported as inline SVG strings and as data URIs, so a page
+can show them without a network request: `ZUDO_MARK_SVG`, `ZUDO_MARK_DARK_SVG`,
+`ZUDO_WORDMARK_SVG`, `ZUDO_WORDMARK_DARK_SVG`, `ZUDO_FAVICON_SVG`, a
+`*_DATA_URI` counterpart for each, plus `ZUDO_SITE_URL`, `zudoLogo(overrides?)`
+and `svgToDataUri(svg)`. The types are `OpenAPIUIOptions`,
+`OpenAPIUIRenderer`, `OpenAPIUIResponse` and `OpenAPILogo`.
+
+## Schemas
+
+`addSchema` converts a `@zudojs/schema` schema into an OpenAPI component and
+registers it.
+
+```typescript
+import {
+  objectSchema,
+  stringSchema,
+  numberSchema,
+  optionalSchema,
+} from "@zudojs/schema";
+
+manager.addSchema(
+  "User",
+  objectSchema({
+    id: stringSchema().uuid(),
+    age: numberSchema().int().min(0),
+    nickname: optionalSchema(stringSchema()),
+  }),
 );
 ```
 
-## Features
+produces
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "format": "uuid" },
+    "age": { "type": "integer", "minimum": 0 },
+    "nickname": { "type": "string" }
+  },
+  "required": ["id", "age"]
+}
+```
+
+Objects, arrays, enums, literals, unions, discriminated unions,
+intersections, records, tuples, sets, optionals, nullables, defaults,
+refinements, transforms, lazy schemas, bigints and the coercion wrappers are
+all converted, along with string and number constraints (`min`, `max`,
+`length`, `pattern`, `format`, `int`, `multipleOf`, `gt`, `lt`). Constraints
+on a coercing schema (`coerce.number().int().min(1)`) are carried through.
+
+A property is listed in `required` exactly when the object parser rejects
+its absence: fields wrapped in `optional`, fields with a `default`, and
+`any` / `unknown` fields are left out, and `.required()` forces every key
+back on. A default supplied as a factory (`.default(() => new Date())`) is
+invoked once and its value emitted.
+
+Anything that cannot be expressed exactly produces a **warning** rather than a
+silent `{}`:
+
+```typescript
+const manager = new OpenAPIManager({
+  info,
+  onSchemaWarning: (name, warnings) => logger.warn({ name, warnings }),
+});
+
+manager.schemaWarnings(); // Map<componentName, warnings>
+```
+
+### Version awareness
+
+3.0 and 3.1 spell several keywords differently, and the difference is not
+cosmetic: the 3.1 spelling in a 3.0 document is either rejected by a strict
+tool or ignored by a lenient one, so the constraint silently disappears from
+the published contract. The converter emits whichever spelling the target
+version defines.
+
+| Constraint       | 3.1.x                        | 3.0.x                                |
+| ---------------- | ---------------------------- | ------------------------------------ |
+| `gt(5)`          | `exclusiveMinimum: 5`        | `minimum: 5, exclusiveMinimum: true` |
+| `lt(10)`         | `exclusiveMaximum: 10`       | `maximum: 10, exclusiveMaximum: true`|
+| `positive()`     | `exclusiveMinimum: 0`        | `minimum: 0, exclusiveMinimum: true` |
+| nullable         | `type: ["string", "null"]`   | `nullable: true`                     |
+| literal          | `const: "yes"`               | `enum: ["yes"]`                      |
+| tuple            | `prefixItems`                | `minItems` / `maxItems`              |
+
+In 3.1 `exclusiveMinimum` carries the bound itself; in 3.0 it is a boolean
+modifier on `minimum`. Emitting the number into a 3.0 document produced a
+keyword of the wrong type, which is how a `gt(5)` constraint used to vanish
+from a 3.0 spec. Both spellings are now correct, and no 3.1-only keyword
+reaches a 3.0 document.
+
+A regular expression's flags have nowhere to go: OpenAPI's `pattern` carries
+the source and nothing else. A `/^abc$/i` pattern would therefore become
+case-*sensitive* in the document — a published contract stricter than the code
+validating against it. Rather than drop the flags silently, the converter
+emits the source and raises a warning naming them.
+
+Recursive schemas are detected and reported rather than overflowing the stack —
+register the recursive type as a named component and reference it with `$ref`.
+
+Use `convertSchema` directly when you want the conversion without the
+registry:
+
+```typescript
+import { convertSchema } from "@zudojs/openapi";
+
+const { schema, warnings } = convertSchema(mySchema, { version: "3.0.3" });
+```
+
+> The converter reads `@zudojs/schema`'s runtime fields structurally rather
+> than importing its classes, which keeps it usable with any compatible
+> object. The field names it depends on are listed at the top of
+> `schemaConverter.core.ts` and covered by tests.
+
+## Validation
+
+```typescript
+const result = manager.validate();
+result.valid; // boolean
+result.errors; // OpenAPIValidationIssue[]
+result.warnings; // OpenAPIValidationIssue[]
+```
+
+The validator checks:
+
+- required document fields, and that `openapi` is a supported version
+- that every operation declares at least one response, keyed by a status
+  code, a `4XX`-style range, or `default`, each with a description
+- that path templates and `in: "path"` parameters agree in both directions —
+  the classic "`{id}` is in the path but nowhere in `parameters`" mistake
+- that path parameters are marked required, and that no parameter is declared
+  twice in one list (an operation-level parameter may override a path-level
+  one with the same name and location)
+- that no two paths are identical apart from their template parameter names
+  (`/users/{id}` next to `/users/{userId}`)
+- `operationId` uniqueness and length
+- that every `security` requirement names a scheme declared in
+  `components.securitySchemes` — a typo there yields a document that _looks_
+  protected
+- that every local `$ref` resolves within the document
+- that every non-local `$ref` uses a scheme a resolver may reasonably be
+  pointed at — only `http` and `https`. A `$ref` is an instruction to whatever
+  dereferences the document, so `file:///etc/passwd` or
+  `http://169.254.169.254/latest/meta-data/` turns the spec into a file-read or
+  SSRF sink in the resolver downstream. Any other scheme is an **error**; an
+  http(s) or relative reference is legal OpenAPI and so is a **warning**,
+  telling you something outside the document will be fetched
+- that no path still uses `:id` instead of `{id}`
+
+`assertValid` throws an `OpenAPIValidationError` that **carries the issues**:
+
+```typescript
+try {
+  manager.generate(true);
+} catch (error) {
+  if (error instanceof OpenAPIValidationError) {
+    console.error(error.format()); // one line per issue
+    error.issues; // structured
+  }
+}
+```
+
+## Building a document by hand
+
+```typescript
+import { OpenAPIDocumentBuilder } from "@zudojs/openapi";
+
+const document = new OpenAPIDocumentBuilder({
+  info: { title: "Orders API", version: "1.2.0" },
+})
+  .addServer({ url: "https://api.example.com" })
+  .addTag({ name: "orders" })
+  .addSecurityScheme("bearerAuth", { type: "http", scheme: "bearer" })
+  .addSecurity({ bearerAuth: [] })
+  .addSchema("Order", { type: "object" })
+  .addPath("/orders", {
+    get: { responses: { "200": { description: "OK" } } },
+    post: { responses: { "201": { description: "Created" } } },
+  })
+  .build();
+```
+
+The builder and the manager assemble documents through the same registry, so
+both paths produce the same shape and obey the same rules.
+
+## Serialization
+
+`toOpenAPIJSON` and `toOpenAPIYAML` both take a document. The YAML output is
+real YAML — a document is plain maps, arrays and scalars, and strings that YAML
+would reinterpret (`true`, `null`, `1.0`, anything opening with a reserved
+character) are quoted.
+
+## References
+
+```typescript
+import { createComponentReference } from "@zudojs/openapi";
+
+createComponentReference("schemas", "User");
+// { $ref: "#/components/schemas/User" }
+```
+
+Component names are escaped per RFC 6901, so a name containing `/` or `~`
+still produces a pointer that resolves.
+
+## Errors
+
+All errors extend `OpenAPIError` (a `BaseError` from `@zudojs/errors`) and
+default to status 500, not exposed — these are failures while a service builds
+or validates its own specification, not responses to a client request:
+
+`OpenAPIValidationError` · `OpenAPIDocumentError` · `OpenAPIComponentError` ·
+`OpenAPIComponentConflictError` · `OpenAPIReferenceError` ·
+`OpenAPIRouteError` · `OpenAPISchemaError` · `OpenAPISerializationError` ·
+`OpenAPIVersionError` · `OpenAPIOperationError`
 
-- OpenAPI 3.1 spec generation
-- Route documentation decorators
-- Schema integration with `@zudojs/schema`
-- Request/response validation
-- SDK generation
+Each accepts `statusCode` and `expose` overrides.
 
 ## Use Cases
 
-- REST API documentation
-- Client SDK generation
-- API contract validation
-- Developer portals
+- Generating API documentation from route metadata
+- Serving a spec, and a branded Swagger UI or ReDoc page, from your own app
+- Feeding client and server code generators
+- Contract checks in CI

package/dist/index.d.ts

@@ -10,7 +10,11 @@
  * ```ts
  * import { OpenAPIManager } from "@zudojs/openapi";
  *
- * const manager = new OpenAPIManager("3.1.0");
+ * const manager = new OpenAPIManager({
+ *   version: "3.1.0",
+ *   info: { title: "Orders API", version: "1.2.0" },
+ *   servers: [{ url: "https://api.example.com" }],
+ * });
  *
  * manager.addRoute({
  *   method: "get",
@@ -19,32 +23,33 @@
  *     openapi: {
  *       operationId: "users.get",
  *       summary: "Get a user",
- *       responses: { "200": { description: "User found" } },
+ *       parameters: [{ name: "id", in: "path", required: true }],
+ *       responses: {
+ *         "200": { description: "User found" },
+ *         "404": { description: "No such user" },
+ *       },
  *     },
  *   },
  * });
  *
- * const document = manager.generate();
+ * const document = manager.generate(true); // validate while generating
  * const json = manager.toJSON();
+ * const yaml = manager.toYAML();
  * ```
  */
-export { OpenAPIDocumentBuilder } from "./openApiDocument/openApiDocument.builder.js";
-export type { OpenAPIDocumentOptions } from "./openApiDocument/openApiDocument.builder.js";
-export { OpenAPIRegistryImpl } from "./openApiRegistry/openApiRegistry.core.js";
-export type { OpenAPIRegistry, OpenAPIRoute, OpenAPIComponentRegistration, } from "./openApiRegistry/openApiRegistry.type.js";
-export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, } from "./openApiErrors/openApiError.core.js";
-export type { OpenAPIErrorOptions, OpenAPIValidationIssue, } from "./openApiErrors/openApiError.core.js";
-export { DEFAULT_OPENAPI_VERSION, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/openApiConstants.core.js";
-export { toOpenAPIPath, convertRouteToOpenAPI, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
-export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, } from "./openApiRouting/index.js";
-export { convertSchema, createSchemaConverter, } from "./openApiSchema/schemaConverter.core.js";
-export type { SchemaConverter, SchemaConversionResult, } from "./openApiSchema/schemaConverter.core.js";
-export { SchemaRegistryImpl } from "./openApiSchema/schemaRegistry.core.js";
-export type { SchemaRegistry } from "./openApiSchema/schemaRegistry.core.js";
-export { createComponentReference } from "./openApiSchema/references.core.js";
-export { OpenAPIValidatorImpl } from "./openApiValidation/openApiValidator.core.js";
-export type { OpenAPIValidator } from "./openApiValidation/openApiValidator.core.js";
+export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, type OpenAPIUIOptions, type OpenAPIUIRenderer, } from "./openApiUi/index.js";
+export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, type OpenAPIDocumentOptions, } from "./openApiDocument/index.js";
+export { OpenAPIRegistryImpl } from "./openApiRegistry/index.js";
+export type { OpenAPIRegistry, OpenAPIRoute, OpenAPIComponentRegistration, } from "./openApiRegistry/index.js";
+export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, formatIssuePath, type OpenAPIErrorOptions, type OpenAPIValidationIssue, } from "./openApiErrors/index.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/index.js";
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
+export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, } from "./openApiRouting/index.js";
+export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./openApiSchema/index.js";
+export type { SchemaConverter, SchemaConversionResult, SchemaConversionOptions, SchemaRegistry, SchemaRegistryOptions, ComponentSection, } from "./openApiSchema/index.js";
+export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidation/index.js";
+export type { OpenAPIValidator, OpenAPIValidationResult, } from "./openApiValidation/index.js";
 export { toOpenAPIJSON, toOpenAPIYAML, } from "./openApiSerialization/openApiSerializer.core.js";
-export { OpenAPIManager } from "./openApiHttp/openApiHttpAdapter.core.js";
-export type { OpenAPIVersion, OpenAPIDocument, OpenAPIComponents, OpenAPISecurityRequirement, OpenAPIParameterLocation, OpenAPIResponse, OpenAPIParameter, OpenAPIRequestBody, OpenAPIMediaType, OpenAPIEncoding, OpenAPIHeader, OpenAPILink, OpenAPIExample, OpenAPIPaths, OpenAPIPathItem, OpenAPIOperation, OpenAPIResponses, OpenAPIServer, OpenAPIServerVariable, OpenAPIInfo, OpenAPIContact, OpenAPILicense, OpenAPIExternalDocumentation, OpenAPISchema, OpenAPIDiscriminator, OpenAPIXml, OpenAPISecurityScheme, OpenAPIOAuthFlows, OpenAPIOAuthFlow, OpenAPITag, OpenAPIReference, } from "./openApiTypes/openApiTypes.core.js";
+export { OpenAPIManager, createOpenAPIManager, type OpenAPIManagerOptions, type OpenAPIDocumentResponse, type OpenAPIUIResponse, } from "./openApiHttp/index.js";
+export type { OpenAPIVersion, OpenAPIDocument, OpenAPIComponents, OpenAPISecurityRequirement, OpenAPIParameterLocation, OpenAPIResponse, OpenAPIParameter, OpenAPIRequestBody, OpenAPIMediaType, OpenAPIEncoding, OpenAPIHeader, OpenAPILink, OpenAPIExample, OpenAPIPaths, OpenAPIPathItem, OpenAPIOperation, OpenAPIResponses, OpenAPIServer, OpenAPIServerVariable, OpenAPIInfo, OpenAPILogo, OpenAPIContact, OpenAPILicense, OpenAPIExternalDocumentation, OpenAPISchema, OpenAPIDiscriminator, OpenAPIXml, OpenAPISecurityScheme, OpenAPIOAuthFlows, OpenAPIOAuthFlow, OpenAPITag, OpenAPIReference, } from "./openApiTypes/openApiTypes.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -10,7 +10,11 @@
  * ```ts
  * import { OpenAPIManager } from "@zudojs/openapi";
  *
- * const manager = new OpenAPIManager("3.1.0");
+ * const manager = new OpenAPIManager({
+ *   version: "3.1.0",
+ *   info: { title: "Orders API", version: "1.2.0" },
+ *   servers: [{ url: "https://api.example.com" }],
+ * });
  *
  * manager.addRoute({
  *   method: "get",
@@ -19,24 +23,38 @@
  *     openapi: {
  *       operationId: "users.get",
  *       summary: "Get a user",
- *       responses: { "200": { description: "User found" } },
+ *       parameters: [{ name: "id", in: "path", required: true }],
+ *       responses: {
+ *         "200": { description: "User found" },
+ *         "404": { description: "No such user" },
+ *       },
  *     },
  *   },
  * });
  *
- * const document = manager.generate();
+ * const document = manager.generate(true); // validate while generating
  * const json = manager.toJSON();
+ * const yaml = manager.toYAML();
  * ```
  */
-export { OpenAPIDocumentBuilder } from "./openApiDocument/openApiDocument.builder.js";
-export { OpenAPIRegistryImpl } from "./openApiRegistry/openApiRegistry.core.js";
-export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, } from "./openApiErrors/openApiError.core.js";
-export { DEFAULT_OPENAPI_VERSION, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/openApiConstants.core.js";
-export { toOpenAPIPath, convertRouteToOpenAPI, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
-export { convertSchema, createSchemaConverter, } from "./openApiSchema/schemaConverter.core.js";
-export { SchemaRegistryImpl } from "./openApiSchema/schemaRegistry.core.js";
-export { createComponentReference } from "./openApiSchema/references.core.js";
-export { OpenAPIValidatorImpl } from "./openApiValidation/openApiValidator.core.js";
+/* ─── Documentation UI & branding ──────────────────────────────────────── */
+export { renderOpenAPIUI, zudoLogo, svgToDataUri, ZUDO_MARK_SVG, ZUDO_MARK_DARK_SVG, ZUDO_WORDMARK_SVG, ZUDO_WORDMARK_DARK_SVG, ZUDO_FAVICON_SVG, ZUDO_MARK_DATA_URI, ZUDO_MARK_DARK_DATA_URI, ZUDO_WORDMARK_DATA_URI, ZUDO_WORDMARK_DARK_DATA_URI, ZUDO_FAVICON_DATA_URI, ZUDO_SITE_URL, } from "./openApiUi/index.js";
+/* ─── Document builder ──────────────────────────────────────────────────── */
+export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, } from "./openApiDocument/index.js";
+/* ─── Registry ──────────────────────────────────────────────────────────── */
+export { OpenAPIRegistryImpl } from "./openApiRegistry/index.js";
+/* ─── Errors ────────────────────────────────────────────────────────────── */
+export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, formatIssuePath, } from "./openApiErrors/index.js";
+/* ─── Constants ─────────────────────────────────────────────────────────── */
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants/index.js";
+/* ─── Routing ───────────────────────────────────────────────────────────── */
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, OpenAPIRouteScannerImpl, } from "./openApiRouting/index.js";
+/* ─── Schema conversion ─────────────────────────────────────────────────── */
+export { convertSchema, createSchemaConverter, isVersion31, SchemaRegistryImpl, createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./openApiSchema/index.js";
+/* ─── Validation ────────────────────────────────────────────────────────── */
+export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidation/index.js";
+/* ─── Serialization ─────────────────────────────────────────────────────── */
 export { toOpenAPIJSON, toOpenAPIYAML, } from "./openApiSerialization/openApiSerializer.core.js";
-export { OpenAPIManager } from "./openApiHttp/openApiHttpAdapter.core.js";
+/* ─── Manager ───────────────────────────────────────────────────────────── */
+export { OpenAPIManager, createOpenAPIManager, } from "./openApiHttp/index.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiComponents/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Reusable OpenAPI component helpers.
  */
-export { createComponentReference } from "../openApiSchema/references.core.js";
-export type { SchemaRegistry } from "../openApiSchema/schemaRegistry.core.js";
+export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, type ComponentSection, } from "../openApiSchema/references.core.js";
+export type { SchemaRegistry, SchemaRegistryOptions, } from "../openApiSchema/schemaRegistry.core.js";
 export { SchemaRegistryImpl } from "../openApiSchema/schemaRegistry.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiComponents/index.js

@@ -3,6 +3,6 @@
  *
  * Reusable OpenAPI component helpers.
  */
-export { createComponentReference } from "../openApiSchema/references.core.js";
+export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "../openApiSchema/references.core.js";
 export { SchemaRegistryImpl } from "../openApiSchema/schemaRegistry.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiConstants/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * @zudojs/openapi/openApiConstants
  */
-export { DEFAULT_OPENAPI_VERSION, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiConstants/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/openapi/openApiConstants
  */
-export { DEFAULT_OPENAPI_VERSION, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
+export { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, MAX_OPERATION_ID_LENGTH, COMPONENT_REF_PREFIX, DEFAULT_MEDIA_TYPE, STATUS_CODE_CATEGORIES, RESPONSE_KEY_PATTERN, PATH_TEMPLATE_PARAMETER, DEFAULT_SERVER_URL, DOCUMENT_CACHE_TTL_MS, } from "./openApiConstants.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiConstants/openApiConstants.core.d.ts

@@ -8,7 +8,13 @@
  */
 export declare const DEFAULT_OPENAPI_VERSION: "3.1.0";
 /**
- * Maximum operation ID length allowed by OpenAPI.
+ * Every specification version this package can emit and validate.
+ */
+export declare const SUPPORTED_OPENAPI_VERSIONS: readonly ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0", "3.1.1"];
+/**
+ * Maximum operation ID length. Not a specification limit — a practical one:
+ * operation IDs become function names in generated clients, and tooling
+ * routinely truncates beyond this.
  */
 export declare const MAX_OPERATION_ID_LENGTH = 128;
 /**
@@ -20,7 +26,7 @@ export declare const COMPONENT_REF_PREFIX = "#/components";
  */
 export declare const DEFAULT_MEDIA_TYPE = "application/json";
 /**
- * Status code categories.
+ * Status code categories, usable as OpenAPI response keys.
  */
 export declare const STATUS_CODE_CATEGORIES: {
     readonly INFORMATIONAL: "1XX";
@@ -29,12 +35,18 @@ export declare const STATUS_CODE_CATEGORIES: {
     readonly CLIENT_ERROR: "4XX";
     readonly SERVER_ERROR: "5XX";
 };
+/** A response key is valid when it is `default`, `NXX`, or a status code. */
+export declare const RESPONSE_KEY_PATTERN: RegExp;
+/** OpenAPI path template parameter, e.g. `{orderId}`. */
+export declare const PATH_TEMPLATE_PARAMETER: RegExp;
 /**
  * Default server URL.
  */
 export declare const DEFAULT_SERVER_URL = "http://localhost";
 /**
- * Cache TTL for generated documents (5 minutes).
+ * Default time a generated document stays cached before it is rebuilt.
+ *
+ * Applied by `OpenAPIManager`; pass `cacheTtlMs` to change or disable it.
  */
 export declare const DOCUMENT_CACHE_TTL_MS: number;
 //# sourceMappingURL=openApiConstants.core.d.ts.map