Skip to main content

@rtorcato/api-openapi v1.0.0

Interfaces​

OpenApiInfo​

Defined in: builder.ts:16

Properties​

title​

title: string

Defined in: builder.ts:17

version​

version: string

Defined in: builder.ts:18

description?​

optional description?: string

Defined in: builder.ts:19

ServerObject​

Defined in: builder.ts:22

Properties​

url​

url: string

Defined in: builder.ts:23

description?​

optional description?: string

Defined in: builder.ts:24

TagObject​

Defined in: builder.ts:27

Properties​

name​

name: string

Defined in: builder.ts:28

description?​

optional description?: string

Defined in: builder.ts:29

RouteResponse​

Defined in: builder.ts:32

Properties​

description​

description: string

Defined in: builder.ts:34

Human-readable description (required by OpenAPI).

schema?​

optional schema?: ZodSchema

Defined in: builder.ts:36

Response body schema. Omit for empty responses (e.g. 204).

mediaType?​

optional mediaType?: string

Defined in: builder.ts:38

Media type for the response body. Default: application/json.

RouteRequest​

Defined in: builder.ts:41

Properties​

params?​

optional params?: ZodSchema

Defined in: builder.ts:43

Path parameters — an object schema; each property becomes a path parameter (always required).

query?​

optional query?: ZodSchema

Defined in: builder.ts:45

Query parameters — an object schema; each property becomes a query parameter.

headers?​

optional headers?: ZodSchema

Defined in: builder.ts:47

Header parameters — an object schema; each property becomes a header parameter.

body?​

optional body?: ZodSchema

Defined in: builder.ts:49

Request body schema.

bodyMediaType?​

optional bodyMediaType?: string

Defined in: builder.ts:51

Media type for the request body. Default: application/json.

bodyRequired?​

optional bodyRequired?: boolean

Defined in: builder.ts:53

Whether the request body is required. Default: true.

RouteConfig​

Defined in: builder.ts:58

Properties​

method​

method: HttpMethod

Defined in: builder.ts:59

path​

path: string

Defined in: builder.ts:61

Path, in Express (/users/:id) or OpenAPI (/users/{id}) style — both are accepted.

summary?​

optional summary?: string

Defined in: builder.ts:62

description?​

optional description?: string

Defined in: builder.ts:63

operationId?​

optional operationId?: string

Defined in: builder.ts:64

tags?​

optional tags?: string[]

Defined in: builder.ts:65

request?​

optional request?: RouteRequest

Defined in: builder.ts:66

responses​

responses: Record<string | number, RouteResponse>

Defined in: builder.ts:68

Responses keyed by status code (or default). At least one is recommended.

OpenApiDocumentConfig​

Defined in: builder.ts:71

Properties​

info​

info: OpenApiInfo

Defined in: builder.ts:72

servers?​

optional servers?: ServerObject[]

Defined in: builder.ts:73

routes​

routes: RouteConfig[]

Defined in: builder.ts:74

components?​

optional components?: Record<string, unknown>

Defined in: builder.ts:76

Merged into the document's components (e.g. securitySchemes).

security?​

optional security?: Record<string, string[]>[]

Defined in: builder.ts:78

Top-level security requirements.

tags?​

optional tags?: TagObject[]

Defined in: builder.ts:79

OpenApiDocument​

Defined in: builder.ts:82

Properties​

openapi​

openapi: "3.1.0"

Defined in: builder.ts:83

info​

info: OpenApiInfo

Defined in: builder.ts:84

servers?​

optional servers?: ServerObject[]

Defined in: builder.ts:85

paths​

paths: Record<string, Record<string, unknown>>

Defined in: builder.ts:86

components?​

optional components?: Record<string, unknown>

Defined in: builder.ts:87

security?​

optional security?: Record<string, string[]>[]

Defined in: builder.ts:88

tags?​

optional tags?: TagObject[]

Defined in: builder.ts:89

ScalarOptions​

Defined in: index.ts:1

Properties​

title?​

optional title?: string

Defined in: index.ts:2

theme?​

optional theme?: "default" | "alternate" | "moon" | "purple" | "solarized" | "bluePlanet" | "deepSpace" | "saturn" | "kepler" | "mars" | "none"

Defined in: index.ts:3

cdnUrl?​

optional cdnUrl?: string

Defined in: index.ts:15

SwaggerOptions​

Defined in: index.ts:18

Properties​

title?​

optional title?: string

Defined in: index.ts:19

cssCdnUrl?​

optional cssCdnUrl?: string

Defined in: index.ts:20

jsCdnUrl?​

optional jsCdnUrl?: string

Defined in: index.ts:21

DocsHtmlOptions​

Defined in: index.ts:74

Properties​

specUrl​

specUrl: string

Defined in: index.ts:76

URL where the OpenAPI JSON spec is served (e.g. /openapi.json).

ui?​

optional ui?: "scalar" | "swagger"

Defined in: index.ts:78

Which UI to render. Default: 'scalar'.

title?​

optional title?: string

Defined in: index.ts:80

Page title. Default: 'API Reference'.

theme?​

optional theme?: "default" | "alternate" | "moon" | "purple" | "solarized" | "bluePlanet" | "deepSpace" | "saturn" | "kepler" | "mars" | "none"

Defined in: index.ts:82

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

cdnUrl?​

optional cdnUrl?: string

Defined in: index.ts:84

Scalar bundle CDN URL.

cssCdnUrl?​

optional cssCdnUrl?: string

Defined in: index.ts:86

Swagger UI stylesheet CDN URL.

jsCdnUrl?​

optional jsCdnUrl?: string

Defined in: index.ts:88

Swagger UI bundle CDN URL.

Type Aliases​

HttpMethod​

HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options"

Defined in: builder.ts:56

Functions​

buildOpenApiDocument()​

buildOpenApiDocument(config): OpenApiDocument

Defined in: builder.ts:208

Build an OpenAPI 3.1 document from route definitions with Zod request/response schemas.

Parameters​

config​

OpenApiDocumentConfig

Returns​

OpenApiDocument

Example​

import { z } from 'zod'
import { buildOpenApiDocument } from '@rtorcato/api-openapi'

const doc = buildOpenApiDocument({
  info: { title: 'Users API', version: '1.0.0' },
  routes: [
    {
      method: 'get',
      path: '/users/:id',
      request: { params: z.object({ id: z.string() }) },
      responses: {
        200: { description: 'A user', schema: z.object({ id: z.string(), name: z.string() }) },
        404: { description: 'Not found' },
      },
    },
  ],
})
// → serve `doc` as JSON, and render it with `docsHtml({ specUrl })`

generateSwaggerHtml()​

generateSwaggerHtml(spec, options?): string

Defined in: index.ts:24

Parameters​

spec​

object

options?​

SwaggerOptions = {}

Returns​

string

generateScalarHtml()​

generateScalarHtml(spec, options?): string

Defined in: index.ts:49

Parameters​

spec​

object

options?​

ScalarOptions = {}

Returns​

string

docsHtml()​

docsHtml(options): string

Defined in: index.ts:103

Generate docs HTML that loads the spec from a URL (rather than inlining it).

The counterpart to generateScalarHtml / generateSwaggerHtml: pair it with a route that serves the spec JSON at specUrl so the page and the spec are fetched separately.

Parameters​

options​

DocsHtmlOptions

Returns​

string

Example​

app.get('/openapi.json', (_req, res) => res.json(doc))
app.get('/docs', (_req, res) => res.type('html').send(docsHtml({ specUrl: '/openapi.json' })))