ArctonArcton
Referencia de la API

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

Parámetros

ParámetroTipoDescripción
optionsOpenAPIOptionsRequerido — 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

CampoTipoDefaultDescripción
infoOpenAPIInfo—Requerido — ver DocumentOptions.
serversobject[]—Ver DocumentOptions.
tagsobject[]—Ver DocumentOptions.
securityobject[]—Ver DocumentOptions.
document.pathstring'/openapi.json'Dónde se sirve el documento en sí.
docsScalarOptions | 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

CampoTipoDescripción
titlestringEl nombre de la API.
versionstringLa versión propia de la API — no está relacionada con la versión del spec de OpenAPI (3.1.0, siempre asignada automáticamente).
descriptionstringOpcional.

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

CampoTipoDescripción
infoOpenAPIInfoVer OpenAPIInfo.
serversobject[]Server Objects de OpenAPI, pasados tal cual se dan.
tagsobject[]Tag Objects de OpenAPI, pasados tal cual se dan.
securityobject[]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

CampoTipoDefaultDescripción
pageTitlestring'Scalar API Reference'El <title> de la página /docs.
cdnstringjsDelivrDesde dónde se carga el bundle de JS de Scalar — asígnalo para apuntar a un build self-hosted.
configurationobject{}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ámetroTipoDescripción
recordsreadonly RouteRecord[]Típicamente el resultado de routesOf(app).
optionsDocumentOptionsVer 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

CampoTipoDescripción
methodHttpMethodUn método concreto — app.all() produce un record por cada método que registra, nunca un record de "cualquier método".
pathstringEl path final de la ruta, con todo prefijo de montaje ya aplicado.
params/query/bodyStandardSchemaV1Las instancias de schema originales, no una forma convertida — ver StandardSchemaV1.
bodyContentRecord<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.
bodyOptionalbooleantrue cuando la ruta acepta una request sin body — su requestBody se documenta sin required.
responseRecord<number, StandardSchemaV1>Normalizado desde RouteOptions.response — siempre indexado por status, incluso cuando se dio un schema suelto.
detailRouteDetailVer 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.

En esta página