Skip to main content

@rtorcato/api-openapi-express v1.0.0

Interfaces​

MountOpenAPIOptions​

Defined in: index.ts:43

Properties​

doc​

doc: object

Defined in: index.ts:45

The OpenAPI spec object to serve. Build it with @rtorcato/api-openapi's buildOpenApiDocument, or ingest legacy JSDoc via specFromJsDoc.

ui?​

optional ui?: "scalar" | "swagger"

Defined in: index.ts:47

Which UI to render. Default: 'scalar'.

specPath?​

optional specPath?: string

Defined in: index.ts:49

Path that serves the raw OpenAPI JSON. Default: /openapi.json.

docsPath?​

optional docsPath?: string

Defined in: index.ts:51

Path that serves the docs UI HTML. Default: /docs.

title?​

optional title?: string

Defined in: index.ts:53

Page title.

theme?​

optional theme?: any

Defined in: index.ts:55

Scalar theme (ignored for ui: 'swagger').

cdnUrl?​

optional cdnUrl?: string

Defined in: index.ts:57

Scalar bundle CDN URL.

cssCdnUrl?​

optional cssCdnUrl?: string

Defined in: index.ts:59

Swagger UI stylesheet CDN URL.

jsCdnUrl?​

optional jsCdnUrl?: string

Defined in: index.ts:61

Swagger UI bundle CDN URL.


SwaggerJsDocOptions​

Defined in: index.ts:98

Properties​

definition​

definition: Record<string, unknown>

Defined in: index.ts:100

The base OpenAPI document (openapi, info, servers, components, …).

apis​

apis: string[]

Defined in: index.ts:102

Globs/paths to files with JSDoc @openapi / @swagger annotations to ingest.

Functions​

serveApiDocs()​

serveApiDocs(spec, options?): Router

Defined in: index.ts:18

Parameters​

spec​

object

options?​

any

Returns​

Router


serveSwaggerDocs()​

serveSwaggerDocs(spec, options?): Router

Defined in: index.ts:28

Parameters​

spec​

object

options?​

any

Returns​

Router


mountOpenAPI()​

mountOpenAPI(app, options): void

Defined in: index.ts:79

Mount OpenAPI docs directly onto an Express app or router: serves the raw spec JSON at specPath and the docs UI (which fetches that JSON) at docsPath.

Unlike serveApiDocs / serveSwaggerDocs (which return a self-contained Router with a relative /openapi.json), this wires both routes onto a target you already have and points the UI at an absolute specPath.

Example​

import { mountOpenAPI } from '@rtorcato/api-openapi-express'
mountOpenAPI(app, { doc, title: 'My API' })
// → GET /openapi.json (spec) and GET /docs (Scalar UI)

Parameters​

app​

MountTarget

options​

MountOpenAPIOptions

Returns​

void


specFromJsDoc()​

specFromJsDoc(options): Promise<object>

Defined in: index.ts:120

Build an OpenAPI spec from JSDoc-annotated source files via swagger-jsdoc, for older projects that document routes with @openapi comments rather than Zod schemas.

swagger-jsdoc is an optional peer dependency — install it only if you use this helper.

Example​

const doc = await specFromJsDoc({
definition: { openapi: '3.1.0', info: { title: 'My API', version: '1.0.0' } },
apis: ['./src/routes/*.ts'],
})
mountOpenAPI(app, { doc })

Parameters​

options​

SwaggerJsDocOptions

Returns​

Promise<object>