ArctonArcton
API Reference

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): RouteAwareMiddleware

Parameters

ParameterTypeDescription
optionsOpenAPIOptionsRequired — 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

FieldTypeDefaultDescription
infoOpenAPIInfo—Required — see DocumentOptions.
serversobject[]—See DocumentOptions.
tagsobject[]—See DocumentOptions.
securityobject[]—See DocumentOptions.
document.pathstring'/openapi.json'Where the document itself is served.
docsScalarOptions | 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

FieldTypeDescription
titlestringThe API's name.
versionstringThe API's own version — unrelated to the OpenAPI spec version (3.1.0, always set for you).
descriptionstringOptional.

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

FieldTypeDescription
infoOpenAPIInfoSee OpenAPIInfo.
serversobject[]OpenAPI Server Objects, passed through as given.
tagsobject[]OpenAPI Tag Objects, passed through as given.
securityobject[]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

FieldTypeDefaultDescription
pageTitlestring'Scalar API Reference'The <title> of the /docs page.
cdnstringjsDelivrWhere Scalar's JS bundle is loaded from — set to point at a self-hosted build.
configurationobject{}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

ParameterTypeDescription
recordsreadonly RouteRecord[]Typically the result of routesOf(app).
optionsDocumentOptionsSee 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

FieldTypeDescription
methodHttpMethodOne concrete method — app.all() produces one record per method it registers, never an "any method" record.
pathstringThe route's final path, with every mounting prefix already applied.
params/query/bodyStandardSchemaV1The original schema instances, not a converted form — see StandardSchemaV1.
bodyContentRecord<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.
bodyOptionalbooleantrue when the route accepts a request with no body — its requestBody is documented without required.
responseRecord<number, StandardSchemaV1>Normalized from RouteOptions.response — always keyed by status, even when a bare schema was given.
detailRouteDetailSee 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.

On this page