ArctonArcton
Integrations

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/openapi

Basic usage

Register openapi() with app.use():

index.ts
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.

On this page