ArctonArcton
Integraciones

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

Uso básico

Registra openapi() con 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 })

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.

En esta página