@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.

Parameters

app

MountTarget

options

MountOpenAPIOptions

Returns

void

Example

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

---

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.

Parameters

options

SwaggerJsDocOptions

Returns

Promise<object>

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 })