Options for OpenAPI document generation.
title: string
API title (required, defaults to 'API').
version: string
API version (required, defaults to '1.0.0').
description: string
API description.
servers: readonly { readonly url: string; readonly description?: string; }[]
Server URLs.
securitySchemes: Record<string, unknown>
Security schemes.
security: readonly SecurityRequirement[]
Document-level security requirements, inherited by every operation whose
route does not declare schema.security. Names must match keys of
OpenApiGeneratorOptions.securitySchemes.
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.
A guard brands itself with RouteSecurityMetadata (every guard
@setu-ts/auth-plugin ships does); when this option is set, a route
carrying a guard that requires authentication is documented as needing
scheme, and one carrying a guard that marks it public is documented with
an empty requirement.
scheme must be a key of OpenApiGeneratorOptions.securitySchemes —
a guard cannot know what the document calls its scheme, so the name is
configured here rather than inferred.
Only ROUTE-level middleware is inspected. Middleware added through
app.middleware.add() is not visible on a route and is not consulted;
that is correct for authMiddleware(), which populates the principal
rather than enforcing anything.
A requirement declared on the route's own schema.security always wins.
exclude: readonly string[]
Router paths to leave out of the generated document.
Matched exactly against the fully-resolved router pattern, which is
router-style rather than an OpenAPI template (/todos/:id, not
/todos/{id}) and INCLUDES any router.group() prefix — a route
registered as get('/metrics') inside group('/internal', …) is matched
only by '/internal/metrics'. Every method registered on an excluded path
is omitted. An entry matching no route is silently ignored.
excludeOwners: readonly string[]
Plugin names whose routes are left out of the generated document,
matched against RouteInfo.owner.
Defaults to ['health-plugin', 'metrics-plugin'], so an application's
operational surface (/health, /live, /ready, /metrics) does not
flow into every client generated from the document. Pass [] to document
them again.
Owners rather than paths, because those endpoints are configurable: a static path list would silently stop excluding a renamed one.
deriveRequestSchemas: boolean
Fills each operation's requestBody and parameters from the validation
middleware actually guarding its route, so a route that already carries
validateBody(schema) does not have to repeat that schema in
schema.body.
A middleware brands itself with RouteValidationMetadata (every helper
@setu-ts/validation-plugin ships does). A value DECLARED on the route's
own schema always wins, per field.
cookies brands are read and ignored: RouteSchema has no cookies
field, so there is no declared counterpart, and @setu-ts/sdk's client
generator refuses an in: 'cookie' parameter outright — emitting one
would turn a working document into a codegen failure.
Unlike OpenApiGeneratorOptions.deriveSecurity this is ON by
default, because nothing has to be configured for it: a security
requirement names a scheme that cannot be inferred from a guard, while the
schema on the route IS the schema the document wants.