OpenAPI & Scalar
Genera un documento OpenAPI 3.1 a partir de los schemas que ya tienen tus rutas, y sírvelo a través de Scalar.
@arcton/openapi construye un documento OpenAPI 3.1 a partir de las rutas
con las que termina una app, y sirve una UI interactiva de
Scalar que lo lee. No hay ningún schema separado que
mantener — el documento se genera a partir de los mismos schemas
params/query/body con los que ya valida una ruta, más un contrato
response opcional.
@arcton/core no sabe que este paquete existe. openapi() es un
middleware común: regístralo con app.use() y
responde él mismo GET /openapi.json y GET /docs.
Instalación
bun add @arcton/openapiUso básico
Registra openapi() con 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 })Esto sirve GET /openapi.json (el documento) y GET /docs (Scalar, leyendo
ese mismo documento — nunca una segunda copia).
Al ser un middleware, corre en orden de registro como cualquier otro: uno registrado después de un middleware de autenticación queda protegido por él; uno registrado antes es público.
Documentar una ruta
params, query y body ya se documentan solos — lo que le pasás a
Arcton para validar una ruta es exactamente lo que termina en el documento
generado. Un body declarado como schema se documenta como application/json;
declarado con content, se documenta cada media type que acepta la ruta con su
propio schema — ver
Aceptar media types específicos.
Dos campos más, ambos solo de documentación, completan una operación:
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 es un mapa de status → schema; un schema suelto es un atajo para
{ 200: schema }. detail mapea operationId/summary/description/
tags/deprecated a la operación de OpenAPI. Ninguno de los dos se valida
en runtime — un handler que devuelve algo distinto responde exactamente
igual que si no existieran. Ver
response/detail y
RouteDetail.
Si omites response, la documentación incluye igualmente una respuesta 200
genérica, pero no puede deducir la forma del valor retornado: los tipos de
TypeScript no existen en runtime y ejecutar el handler para muestrearlo podría
requerir contexto o producir efectos secundarios. Declara response cuando
quieras documentar el schema o códigos de estado concretos.
Un response declarado es el contrato completo: { 404: schema } documenta
solo un 404, sin agregar un 200 implícito.
Requisitos del schema
Convertir un schema a OpenAPI depende de Standard JSON
Schema, una interfaz hermana de
Standard Schema, la que Arcton ya usa para
validar — Zod 4.6+ y ArkType 2.2+ la implementan de forma nativa. Valibot
todavía no; envuelve un schema con toStandardJsonSchema() de
@valibot/to-json-schema para
sumarse.
Un schema que no la implementa — o cuya forma no tiene equivalente en JSON
Schema, como un transform de Zod en la salida — degrada a un schema vacío
({}) en vez de romper el build. Un parámetro de path o un body sigue
apareciendo en el documento con su nombre y ubicación; solo su tipo queda sin
especificar. Un schema de query es la excepción: sus parámetros se listan
leyendo las propiedades del schema, así que uno sin JSON Schema, o que no es
un objeto plano (una unión, por ejemplo), no agrega ningún parámetro de query.
Ver Standard JSON
Schema.
Configurando los paths
Ambas rutas son configurables, y la UI de Scalar puede desactivarse por completo:
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 // solo se sirve /openapi.json
})
)
app.listen()Configurando Scalar
La configuración propia de Scalar — theme, título de página, desde qué CDN
se carga su bundle — se mantiene separada de info/servers/tags del
documento, bajo 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 se pasa directo a Scalar — ver la documentación de
configuración propia de
Scalar
para cada opción que acepta. El bundle de JS de Scalar se carga desde un
CDN por defecto; pasa cdn para apuntar a un build self-hosted.
Modules y el árbol de rutas final
El documento refleja el árbol de rutas final de la app, leído la primera vez que se pide — incluyendo las rutas que vienen de modules, correctamente prefijadas:
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()
// documenta GET /api/users/{id}Una ruta wildcard (*rest) no tiene equivalente como path-template de
OpenAPI y se deja fuera del documento, y una ruta
ws() no tiene ningún contrato que documentar
en primer lugar — ambas siguen sirviendo con normalidad, solo que no
aparecen en /openapi.json.
Ver openapi() para la referencia completa de la API.