OpenAPI & Scalar
Generate an OpenAPI 3.1 document from your routes' existing schemas, and serve it through Scalar.
@arcton/openapi builds an OpenAPI 3.1 document from the routes an app
actually ends up with, and serves an interactive Scalar
UI that reads it. There is no separate schema to maintain — the document is
generated from the same params/query/body schemas a route already
validates against, plus an optional response contract.
@arcton/core doesn't know this package exists. openapi() is an ordinary
middleware: register it with app.use() and it
answers GET /openapi.json and GET /docs itself.
Installation
bun add @arcton/openapiBasic usage
Register openapi() with app.use():
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(), name: z.string() }),
handler: ctx => ({ id: ctx.params.id, name: 'Ada' })
})
app.use(
openapi({
info: { title: 'Users API', version: '1.0.0' }
})
)
app.listen({ port: 3000 })This serves GET /openapi.json (the document) and GET /docs (Scalar,
reading that same document — never a second copy of it).
Because it's a middleware, it runs in registration order like any other: one registered after an auth middleware is protected by it, one registered before is public.
Documenting a route
params, query, and body already document themselves — whatever you
pass Arcton to validate a route is exactly what ends up in the generated
document. A body declared as a schema is documented as application/json;
declared with content, each media type the route accepts is documented with
its own schema — see
Accepting specific media types.
Two more fields, both documentation only, round out an operation:
import { Arcton } from '@arcton/core'
import * as z from 'zod'
const app = Arcton()
app.get('/users/:id', {
params: z.object({ id: z.uuid() }),
response: {
200: z.object({ id: z.string(), name: z.string() }),
404: z.object({ message: z.string() })
},
detail: {
operationId: 'getUser',
summary: 'Get user',
tags: ['Users']
},
handler: ctx => ({ id: ctx.params.id, name: 'Ada' })
})
app.listen()response is a status → schema map; a bare schema is shorthand for { 200: schema }. detail maps operationId/summary/description/tags/
deprecated onto the OpenAPI operation. Neither is validated at runtime — a
handler that returns something else still responds exactly as it would
without them. See response/detail
and RouteDetail.
When response is omitted, the documentation still includes a generic 200
response, but it cannot infer the returned value's shape: TypeScript types do
not exist at runtime, and executing the handler to sample it could require
context or cause side effects. Declare response when you want to document a
schema or specific status codes.
A declared response is the whole contract: { 404: schema } documents only a
404, with no implicit 200 added.
Schema requirements
Converting a schema to OpenAPI relies on Standard JSON
Schema, a sibling to the Standard
Schema interface Arcton already validates
with — Zod 4.6+ and ArkType 2.2+ implement it out of the box. Valibot doesn't
yet; wrap a schema with toStandardJsonSchema() from
@valibot/to-json-schema to opt
in.
A schema that doesn't implement it — or one whose shape has no JSON Schema
equivalent, like a Zod transform on the way out — degrades to an empty
schema ({}) rather than failing the build. A path parameter or a body still
appears in the document with its name and location; only its type is
unknown. A query schema is the exception: its parameters are listed by
reading the schema's properties, so one with no JSON Schema, or one that isn't
a plain object (a union, for example), adds no query parameters at all. See
Standard JSON Schema.
Configuring the paths
Both routes are configurable, and the Scalar UI can be turned off entirely:
import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
const app = Arcton()
app.get('/users', () => [])
app.use(
openapi({
info: { title: 'Users API', version: '1.0.0' },
document: { path: '/schema.json' },
docs: { path: '/reference' }
})
)
app.listen()import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
const app = Arcton()
app.get('/users', () => [])
app.use(
openapi({
info: { title: 'Users API', version: '1.0.0' },
docs: false // only /openapi.json is served
})
)
app.listen()Configuring Scalar
Scalar's own configuration — theme, page title, which CDN serves its bundle
— is kept separate from the document's info/servers/tags, under docs:
import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
const app = Arcton()
app.get('/users', () => [])
app.use(
openapi({
info: { title: 'Users API', version: '1.0.0' },
docs: {
pageTitle: 'Users API Reference',
configuration: { theme: 'purple' }
}
})
)
app.listen()configuration is passed straight through to Scalar — see Scalar's own
configuration docs
for every option it accepts. Scalar's JS bundle loads from a CDN by default;
pass cdn to point at a self-hosted build instead.
Modules and the final route tree
The document reflects the app's final route tree, read the first time it's requested — including routes pulled in through modules, correctly prefixed:
import { Arcton } from '@arcton/core'
import { openapi } from '@arcton/openapi'
import * as z from 'zod'
const users = Arcton({ prefix: '/users' })
users.get('/:id', {
response: z.object({ id: z.string() }),
handler: ctx => ({ id: ctx.params.id })
})
const app = Arcton({ prefix: '/api' })
app.use(users)
app.use(openapi({ info: { title: 'API', version: '1.0.0' } }))
app.listen()
// documents GET /api/users/{id}A wildcard route (*rest) has no OpenAPI path-template equivalent and is
left out of the document, and a ws() route has
no contract to document in the first place — both keep serving normally,
they just don't appear at /openapi.json.
See openapi() for the full API reference.