Generates OpenAPI 3.1 documents from route information.
-
addSchema(): voidname: string,schema: unknown
Registers a named schema for deduplication.
-
generate(routes: readonly RouteInfo[]): OpenApiDocument
Generates an OpenAPI document from routes.
Service for generating and caching OpenAPI specifications.
-
addSchema(): voidname: string,schema: unknown
Registers a named schema for deduplication.
-
getSpec(): Readonly<Record<string, unknown>>
Returns the generated OpenAPI specification.
Converts a Zod schema to an OpenAPI 3.1 schema object.
-
transform(): OpenApiSchemaObjectschema: unknown,io?: SchemaIo
Transforms a Zod schema into an OpenAPI schema object.
Creates an OpenAPI plugin that auto-generates OpenAPI 3.1 documentation from registered routes and serves it (with optional Swagger UI).
Generates the Swagger UI HTML page.
Convenience function for one-off Zod to OpenAPI conversion.
Service for generating and retrieving OpenAPI 3.1 specifications.
-
addSchema(): voidname: string,schema: unknown
Registers a named schema for deduplication.
-
getSpec(): Readonly<Record<string, unknown>>
Returns the generated OpenAPI 3.1 document.
OpenAPI 3.1 document structure.
-
components: { readonly schemas?: Record<string, OpenApiSchemaObject>; readonly securitySchemes?: Record<string, unknown>; }
Reusable components.
-
info: { readonly title: string; readonly version: string; readonly description?: string; }
API metadata.
-
openapi: string
OpenAPI version.
-
paths: Record<>string,{ readonly get?: OpenApiOperation; readonly post?: OpenApiOperation; readonly put?: OpenApiOperation; readonly patch?: OpenApiOperation; readonly delete?: OpenApiOperation; readonly head?: OpenApiOperation; readonly options?: OpenApiOperation; }
API paths.
-
security: readonly SecurityRequirement[]
Document-level security requirements, applied to every operation that does not declare its own. An operation opts out with
security: []. -
servers: readonly { readonly url: string; readonly description?: string; }[]
Server URLs.
Options for OpenAPI document generation.
-
deriveRequestSchemas: boolean
Fills each operation's
requestBodyandparametersfrom the validation middleware actually guarding its route, so a route that already carriesvalidateBody(schema)does not have to repeat that schema inschema.body. -
deriveSecurity: { readonly scheme: string; }
Derives each operation's security requirement from the guards actually protecting its route, instead of requiring every route to declare one.
-
description: string
API description.
-
exclude: readonly string[]
Router paths to leave out of the generated document.
-
excludeOwners: readonly string[]
Plugin names whose routes are left out of the generated document, matched against
RouteInfo.owner. -
security: readonly SecurityRequirement[]
Document-level security requirements, inherited by every operation whose route does not declare
schema.security. Names must match keys ofOpenApiGeneratorOptions.securitySchemes. -
securitySchemes: Record<string, unknown>
Security schemes.
-
servers: readonly { readonly url: string; readonly description?: string; }[]
Server URLs.
-
title: string
API title (required, defaults to 'API').
-
version: string
API version (required, defaults to '1.0.0').
OpenAPI operation definition.
-
operationId: string
Unique operation identifier.
-
parameters: readonly OpenApiParameter[]
Path/query parameters.
-
requestBody: OpenApiRequestBody
Request body.
-
responses: Record<string, OpenApiResponse>
Response codes.
-
security: readonly SecurityRequirement[]
Security requirements for this operation — declared on the route's
schema.security, or derived from its branded guards whenOpenApiGeneratorOptions.deriveSecurityis configured (declared wins). Absent when neither applies, which leaves the operation inheriting the document-level requirement; an empty array marks it public, overriding that default. -
summary: string
Operation summary.
-
tags: readonly string[]
Operation tags.
-
x-setu-unrepresentable: readonly { readonly at: string; readonly reason: string; }[]
Machine-readable vendor extension naming the schema nodes on THIS operation the transformer could not represent (a zod
z.date()field, for example). Each entry names the operation (at) and why (reason). The node itself still degrades to an empty schema — never a throw — so a single unrepresentable field cannot take down/openapi.json. Absent when empty.
OpenAPI parameter definition.
-
description: string
Parameter description.
-
in: "path" | "query" | "header" | "cookie"
Parameter location.
-
name: string
Parameter name.
-
required: boolean
Whether parameter is required.
-
schema: OpenApiSchemaObject
Parameter schema.
Options for the OpenAPI plugin.
-
endpoint: string
Path for the Swagger UI HTML page.
-
specEndpoint: string
Path for the JSON spec endpoint.
-
swagger: boolean
Whether to serve the Swagger UI HTML page.
OpenAPI request body definition.
-
content: { readonly application/json: { readonly schema: OpenApiSchemaObject; }; }
Content types.
-
required: boolean
Whether body is required.
OpenAPI response definition.
-
content: { readonly application/json?: { readonly schema: OpenApiSchemaObject; }; }
Response content.
-
description: string
Response description.
OpenAPI 3.1 schema object.
-
$ref: string
Reference to a component schema.
-
additionalProperties: boolean | OpenApiSchemaObject
For objects: additional properties schema.
-
allOf: readonly OpenApiSchemaObject[]
AllOf for intersections.
-
anyOf: readonly OpenApiSchemaObject[]
AnyOf for unions.
-
const: string | number | boolean
Const value.
-
default: unknown
Default value.
-
enum: readonly (string | number | boolean)[]
Enum values.
-
exclusiveMaximum: number
For numbers: exclusive maximum.
-
exclusiveMinimum: number
For numbers: exclusive minimum.
-
format: string
Format (e.g., 'email', 'uri', 'uuid', 'date-time').
-
items: OpenApiSchemaObject
For arrays: schema of items.
-
maxItems: number
For arrays: maximum items.
-
maxLength: number
For strings: maximum length.
-
maximum: number
For numbers: maximum value.
-
minItems: number
For arrays: minimum items.
-
minLength: number
For strings: minimum length.
-
minimum: number
For numbers: minimum value.
-
properties: Record<string, OpenApiSchemaObject>
For objects: properties map.
-
required: readonly string[]
For objects: required property names.
-
type: "string"
| "number"
| "integer"
| "boolean"
| "array"
| "object"
| "null"Type of the value (string, number, integer, boolean, array, object, null).
Options for the OpenAPI service.
-
app: IApplication
The application context for accessing routes.
-
schemas: readonly { readonly name: string; readonly schema: unknown; }[]
Pre-registered schemas from other plugins.
Options for Swagger UI HTML generation.
-
specUrl: string
The URL of the OpenAPI spec JSON.
-
title: string
The title of the page.
Which side of a schema a document site is describing.
Consulted for every schema ZodToOpenApi.transform is about to
convert — the top-level one AND every sub-schema it recurses into.
Usage
import * as OpenAPI_plugin_for_Setu_TS___Auto_generates_OpenAPI_3_1_documentation_from_registered_routes_and_serves_it__with_optional_Swagger_UI__over_HTTP_ from "openapi-plugin/src/index.ts";