OpenAPI
La factory openapi() y sus opciones, de @arcton/openapi.
Resumen
Sirve un documento OpenAPI 3.1 y una UI de Scalar que lo lee, generados a
partir de params/query/body/response/detail propios de cada ruta:
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()Ver OpenAPI & Scalar para la guía orientada al uso.
openapi()
Propósito — construye el middleware que sirve el documento y la página
de Scalar. Se registra con app.use().
Firma
import type { RouteAwareMiddleware } from '@arcton/contracts'
function openapi(options: OpenAPIOptions): RouteAwareMiddlewareParámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
options | OpenAPIOptions | Requerido — como mínimo, info. Ver abajo cada campo. |
Tipo de retorno — un RouteAwareMiddleware.
Comportamiento — responde los requests GET al documento
(document.path, por defecto /openapi.json) y, salvo que se pase
docs: false, a una página de Scalar (docs.path, por defecto /docs) que
carga el documento por URL en vez de embeber una segunda copia. Todo otro
request sigue a next(). El documento se construye una sola vez, en el
primer request que lo pide — con todos los modules ya montados — y nunca por
request. Corre en orden de registro como cualquier middleware, así que uno
registrado después de un middleware de autenticación queda protegido por él.
Errores — no hay error de registro: una ruta en alguno de los mismos
paths queda tapada si openapi() se registró antes que ella, y responde con
normalidad si se registró después. Usar openapi() en cualquier lugar que no
sea app.use() (el middleware propio de una ruta, por ejemplo) lanza
openapi() must be registered with app.use() en el primer request al
documento.
Ejemplo
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
Propósito — el objeto de opciones que acepta openapi().
Firma
interface OpenAPIOptions extends DocumentOptions {
document?: { path?: string }
docs?: (ScalarOptions & { path?: string }) | false
}Campos
| Campo | Tipo | Default | Descripción |
|---|---|---|---|
info | OpenAPIInfo | — | Requerido — ver DocumentOptions. |
servers | object[] | — | Ver DocumentOptions. |
tags | object[] | — | Ver DocumentOptions. |
security | object[] | — | Ver DocumentOptions. |
document.path | string | '/openapi.json' | Dónde se sirve el documento en sí. |
docs | ScalarOptions | false | {} | Las opciones propias de Scalar — ver ScalarOptions — más path (default '/docs'). false sirve solo el documento, sin UI. |
Comportamiento — document y docs se mantienen separados de
info/servers/tags/security a propósito: un lado describe la API, el
otro describe la UI que la lee. Ver Configurar los
paths y Configurar
Scalar.
OpenAPIInfo
Propósito — el objeto info del documento — el único campo requerido
de OpenAPIOptions.
Firma
interface OpenAPIInfo {
title: string
version: string
description?: string
[key: string]: unknown
}Campos
| Campo | Tipo | Descripción |
|---|---|---|
title | string | El nombre de la API. |
version | string | La versión propia de la API — no está relacionada con la versión del spec de OpenAPI (3.1.0, siempre asignada automáticamente). |
description | string | Opcional. |
Comportamiento — cualquier otro campo de info de OpenAPI
(termsOfService, contact, license, ...) se acepta a través del index
signature y se pasa directo al documento, sin validar.
DocumentOptions
Propósito — los campos a nivel de documento que extiende
OpenAPIOptions; también lo que recibe buildDocument()
por sí mismo.
Firma
interface DocumentOptions {
info: OpenAPIInfo
servers?: Record<string, unknown>[]
tags?: Record<string, unknown>[]
security?: Record<string, unknown>[]
}Campos
| Campo | Tipo | Descripción |
|---|---|---|
info | OpenAPIInfo | Ver OpenAPIInfo. |
servers | object[] | Server Objects de OpenAPI, pasados tal cual se dan. |
tags | object[] | Tag Objects de OpenAPI, pasados tal cual se dan. |
security | object[] | Security Requirement Objects de OpenAPI, pasados tal cual se dan. |
Comportamiento — servers/tags/security se copian al documento tal
cual cuando están presentes, y se omiten por completo en caso contrario —
ninguno de los tres tiene un valor por defecto.
ScalarOptions
Propósito — la configuración propia de Scalar, bajo
OpenAPIOptions.docs.
Firma
interface ScalarOptions {
pageTitle?: string
cdn?: string
configuration?: Record<string, unknown>
}Campos
| Campo | Tipo | Default | Descripción |
|---|---|---|---|
pageTitle | string | 'Scalar API Reference' | El <title> de la página /docs. |
cdn | string | jsDelivr | Desde dónde se carga el bundle de JS de Scalar — asígnalo para apuntar a un build self-hosted. |
configuration | object | {} | El objeto de configuración propio de Scalar (theme, sidebar, auth, ...) — ver la documentación de configuración de Scalar. |
Comportamiento — configuration.url siempre se asigna automáticamente,
a partir de OpenAPIOptions.document.path — la página lee el documento por
URL, así que nunca embebe una segunda copia. Cualquier url pasado en
configuration se sobrescribe.
buildDocument()
Propósito — la función de más bajo nivel que openapi() llama
internamente: convierte un conjunto de route records directamente en un
objeto de documento OpenAPI, sin integración HTTP. Útil para escribir el
documento a un archivo en build time, o para testear qué produce un
conjunto de rutas sin levantar un servidor.
Firma
import type { RouteRecord } from '@arcton/contracts'
function buildDocument(
records: readonly RouteRecord[],
options: DocumentOptions
): Record<string, unknown>Parámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
records | readonly RouteRecord[] | Típicamente el resultado de routesOf(app). |
options | DocumentOptions | Ver DocumentOptions arriba. |
Tipo de retorno — un documento OpenAPI 3.1 plano, serializable a JSON.
Ejemplo
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
Propósito — lo que declaró una ruta, guardado junto al árbol de rutas
para que sobreviva después del registro — el árbol en sí solo guarda
handlers ya compuestos. Se lee a través de
routesOf(app); es también lo que recibe el
lo que lee un RouteAwareMiddleware.
Firma
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
}Campos
| Campo | Tipo | Descripción |
|---|---|---|
method | HttpMethod | Un método concreto — app.all() produce un record por cada método que registra, nunca un record de "cualquier método". |
path | string | El path final de la ruta, con todo prefijo de montaje ya aplicado. |
params/query/body | StandardSchemaV1 | Las instancias de schema originales, no una forma convertida — ver StandardSchemaV1. |
bodyContent | Record<string, StandardSchemaV1> | Se define en lugar de body cuando la ruta lista los media types que acepta (keys en minúsculas, sin parámetros). Cada uno pasa a ser una entrada de requestBody.content. |
bodyOptional | boolean | true cuando la ruta acepta una request sin body — su requestBody se documenta sin required. |
response | Record<number, StandardSchemaV1> | Normalizado desde RouteOptions.response — siempre indexado por status, incluso cuando se dio un schema suelto. |
detail | RouteDetail | Ver RouteDetail. |
Comportamiento — una ruta ws() no produce ningún record, al no tener
contrato que describir. Ver routesOf() para
cómo se componen los records entre modules montados.
RouteAwareMiddleware
Propósito — un Middleware que documenta o inspecciona la app en la que
se registra. openapi() devuelve uno.
Firma
interface RouteAwareMiddleware extends Middleware {
bindRoutes(routes: () => readonly RouteRecord[]): void
}Comportamiento — cuando se pasa a use() (con scope o sin él), la app
llama a bindRoutes una sola vez con un lector de su propio
RouteRecord[]. El lector es vivo, así que llamarlo en tiempo de request ve
todo module montado hasta ese momento; @arcton/core nunca necesita saber
qué paquete hay del otro lado.