OpenAPI
The openapi() integration factory and its options, from @arcton/openapi.
Overview
Serve an OpenAPI 3.1 document and a Scalar UI reading it, generated from a
route's own params/query/body/response/detail:
import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
const app = Arcton()
app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.use(openapi({ info: { title: 'API', version: '1.0.0' } }))
app.listen()See OpenAPI & Scalar for the usage-first guide.
openapi()
Purpose — builds the middleware that serves the document and the Scalar
page. Register it with app.use().
Signature
import type { RouteAwareMiddleware } from '@arcton/contracts'
function openapi(options: OpenAPIOptions): RouteAwareMiddlewareParameters
| Parameter | Type | Description |
|---|---|---|
options | OpenAPIOptions | Required — at minimum, info. See below for every field. |
Return type — a RouteAwareMiddleware.
Behavior — answers GET requests to the document (document.path,
default /openapi.json) and, unless docs: false, to a Scalar page
(docs.path, default /docs) that loads the document by URL rather than
embedding a second copy of it. Every other request goes on to next(). The
document is built once, on the first request for it — after every module has
been mounted — and never per request. It runs in registration order like any
middleware, so one registered after an auth middleware is protected by it.
Errors — no registration error: a route at one of the same paths is
shadowed when openapi() was registered before it, and answers normally
when it was registered after. Using openapi() anywhere but app.use() (a route's own middleware,
for example) throws openapi() must be registered with app.use() on the
first request for the document.
Example
import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
import * as z from 'zod'
const app = Arcton()
app.get('/users/:id', {
params: z.object({ id: z.uuid() }),
response: z.object({ id: z.string() }),
detail: { operationId: 'getUser', tags: ['Users'] },
handler: ctx => ({ id: ctx.params.id })
})
app.use(
openapi({
info: { title: 'Users API', version: '1.0.0' },
docs: { path: '/reference' }
})
)
app.listen({ port: 3000 })OpenAPIOptions
Purpose — the options object accepted by openapi().
Signature
interface OpenAPIOptions extends DocumentOptions {
document?: { path?: string }
docs?: (ScalarOptions & { path?: string }) | false
}Fields
| Field | Type | Default | Description |
|---|---|---|---|
info | OpenAPIInfo | — | Required — see DocumentOptions. |
servers | object[] | — | See DocumentOptions. |
tags | object[] | — | See DocumentOptions. |
security | object[] | — | See DocumentOptions. |
document.path | string | '/openapi.json' | Where the document itself is served. |
docs | ScalarOptions | false | {} | Scalar's own options — see ScalarOptions — plus path (default '/docs'). false serves the document alone, with no UI. |
Behavior — document and docs are kept separate from info/
servers/tags/security on purpose: one side describes the API, the
other describes the UI reading it. See Configuring the
paths and Configuring
Scalar.
OpenAPIInfo
Purpose — the document's info object — the one required field of
OpenAPIOptions.
Signature
interface OpenAPIInfo {
title: string
version: string
description?: string
[key: string]: unknown
}Fields
| Field | Type | Description |
|---|---|---|
title | string | The API's name. |
version | string | The API's own version — unrelated to the OpenAPI spec version (3.1.0, always set for you). |
description | string | Optional. |
Behavior — any other OpenAPI info field (termsOfService, contact,
license, ...) is accepted through the index signature and passed straight
through to the document, unvalidated.
DocumentOptions
Purpose — the document-level fields OpenAPIOptions extends; also what
buildDocument() itself takes.
Signature
interface DocumentOptions {
info: OpenAPIInfo
servers?: Record<string, unknown>[]
tags?: Record<string, unknown>[]
security?: Record<string, unknown>[]
}Fields
| Field | Type | Description |
|---|---|---|
info | OpenAPIInfo | See OpenAPIInfo. |
servers | object[] | OpenAPI Server Objects, passed through as given. |
tags | object[] | OpenAPI Tag Objects, passed through as given. |
security | object[] | OpenAPI Security Requirement Objects, passed through as given. |
Behavior — servers/tags/security are copied onto the document
verbatim when present, and omitted entirely otherwise — none of the three
has a default.
ScalarOptions
Purpose — Scalar's own configuration, under OpenAPIOptions.docs.
Signature
interface ScalarOptions {
pageTitle?: string
cdn?: string
configuration?: Record<string, unknown>
}Fields
| Field | Type | Default | Description |
|---|---|---|---|
pageTitle | string | 'Scalar API Reference' | The <title> of the /docs page. |
cdn | string | jsDelivr | Where Scalar's JS bundle is loaded from — set to point at a self-hosted build. |
configuration | object | {} | Scalar's own configuration object (theme, sidebar, auth, ...) — see Scalar's configuration docs. |
Behavior — configuration.url is always set for you, from
OpenAPIOptions.document.path — the page reads the document by URL, so it
never embeds a second copy of it. Any url passed in configuration is
overridden.
buildDocument()
Purpose — the lower-level function openapi() itself calls: turns a set
of route records straight into an OpenAPI document object, with no HTTP
integration. Useful for writing the document to a file at build time, or for
testing what a set of routes produces without starting a server.
Signature
import type { RouteRecord } from '@arcton/contracts'
function buildDocument(
records: readonly RouteRecord[],
options: DocumentOptions
): Record<string, unknown>Parameters
| Parameter | Type | Description |
|---|---|---|
records | readonly RouteRecord[] | Typically the result of routesOf(app). |
options | DocumentOptions | See DocumentOptions above. |
Return type — a plain, JSON-serializable OpenAPI 3.1 document.
Example
import { Arcton, routesOf } from '@arcton/core'
import { buildDocument } from '@arcton/openapi'
const app = Arcton()
app.get('/users/:id', ctx => ({ id: ctx.params.id }))
const document = buildDocument(routesOf(app), {
info: { title: 'Users API', version: '1.0.0' }
})
await Bun.write('openapi.json', JSON.stringify(document, null, 2))RouteRecord
Purpose — what a route declared, kept alongside the route tree so it
survives after registration — the tree itself stores only composed
handlers. Read through routesOf(app); this is
also what a RouteAwareMiddleware reads.
Signature
import type { StandardSchemaV1 } from '@arcton/contracts'
interface RouteRecord {
method: HttpMethod
path: string
params?: StandardSchemaV1
query?: StandardSchemaV1
body?: StandardSchemaV1
bodyContent?: Record<string, StandardSchemaV1>
bodyOptional?: boolean
response?: Record<number, StandardSchemaV1>
detail?: RouteDetail
}Fields
| Field | Type | Description |
|---|---|---|
method | HttpMethod | One concrete method — app.all() produces one record per method it registers, never an "any method" record. |
path | string | The route's final path, with every mounting prefix already applied. |
params/query/body | StandardSchemaV1 | The original schema instances, not a converted form — see StandardSchemaV1. |
bodyContent | Record<string, StandardSchemaV1> | Set instead of body when the route lists the media types it accepts (keys lowercased, no parameters). Each one becomes an entry of requestBody.content. |
bodyOptional | boolean | true when the route accepts a request with no body — its requestBody is documented without required. |
response | Record<number, StandardSchemaV1> | Normalized from RouteOptions.response — always keyed by status, even when a bare schema was given. |
detail | RouteDetail | See RouteDetail. |
Behavior — a ws() route produces no record, having no contract to
describe. See routesOf() for how records
compose across mounted modules.
RouteAwareMiddleware
Purpose — a Middleware that documents or inspects the app it is
registered on. openapi() returns one.
Signature
interface RouteAwareMiddleware extends Middleware {
bindRoutes(routes: () => readonly RouteRecord[]): void
}Behavior — when it is passed to use() (scoped or not), the app calls
bindRoutes once with a reader of its own RouteRecord[]. The reader is
live, so calling it at request time sees every module mounted by then;
@arcton/core never needs to know which package is on the other end.