Extensions

OpenAPI

A public API deserves a public contract, but a contract maintained by hand drifts from the code the day after it is written. @stone-js/openapi derives the document from the schemas your validation and resources already define, so it stays true by construction.

#Install

terminalbash

npm i @stone-js/openapi

#Derive, do not duplicate

The principle

Two descriptions of the same API, the code and a hand-written spec, cannot stay in sync. Keep one description, the code, and generate the other from it. The contract becomes a view of the implementation, not a parallel artifact.

In Stone.js

OpenApiGenerator builds a valid OpenAPI document from your app: the info block, servers, and the paths and schemas taken from your routes, validation and resources. Serve it at a URL and point any tool at it.

app/openapi.tsts

import { OpenApiGenerator } from '@stone-js/openapi'

export const spec = OpenApiGenerator
  .create({ title: 'Tasks API', version: '1.0.0' })
  .addServer('https://api.example.com')
  .build()   // a valid OpenAPI document

#Serving it

Expose the built document from a route. Tools, machines and agents read it directly; point any OpenAPI viewer (Swagger UI, Scalar) at that URL for a human-friendly, interactive explorer, no separate docs site to keep in sync.

app/OpenApiController.tsdeclarativeimperative

import { EventHandler, Get } from '@stone-js/router'
import { spec } from './openapi'

@EventHandler('/openapi.json')
export class OpenApiController {
  @Get('/')
  document () { return spec }   // the generated OpenAPI document, as JSON
}
import { defineEventHandler, defineRoutes } from '@stone-js/router'
import { spec } from './openapi'

const OpenApiController = () => ({ document: () => spec })

export const routes = defineRoutes([
  [defineEventHandler(OpenApiController, 'document'), { path: '/openapi.json', method: 'GET' }]
])

#Schemas to JSON Schema

Under the hood toJsonSchema converts your validation schemas (Zod and other Standard Schemas) into the JSON Schema the document embeds, which is why the contract stays a faithful view of what you actually validate.

You wrote the schema for validation. The contract is a view of it, not a second copy.