generateOpenApi

generateOpenApi(options) traverses the server manifest, loads each server/api endpoint and server/rpc procedure, and writes an OpenAPI 3.1 document with their paths, parameters, bodies, responses and security. It only publishes schemas registered by the caller in publicSchemas: a contract using a schema outside the registry is an error, so no internal schema leaks accidentally.

It is optional and runs outside the server, in a script or CI. Meeko does not depend on a converter: toJsonSchema receives the one from the schema library, such as @valibot/to-json-schema.

Usage#

// scripts/openapi.ts
import { writeFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import { toJsonSchema } from "@valibot/to-json-schema";
import { discoverServerManifest } from "@meekojs/meeko/build";
import { generateOpenApi } from "@meekojs/meeko/server";
import type { Schema } from "@meekojs/meeko/server";
import * as schemas from "../shared/schemas/public";

const document = await generateOpenApi({
  manifest: await discoverServerManifest(process.cwd()),
  info: { title: "Store API", version: "1.4.0" },
  publicSchemas: schemas,
  toJsonSchema: (schema: Schema) => toJsonSchema(schema as never),
  load: (file) => import(pathToFileURL(file).href),
});
await writeFile("openapi.json", JSON.stringify(document, null, 2));

Run it with a TypeScript loader (npx tsx scripts/openapi.ts): load imports .ts files from server/.

Type#

function generateOpenApi(options: OpenApiOptions): Promise<Record<string, unknown>>

interface OpenApiOptions {
	manifest: ServerManifest
	info: { title: string; version: string }
	publicSchemas: Readonly<Record<string, Schema>>
	toJsonSchema(schema: Schema): unknown
	load: ServerModuleLoader
	cookieName?: string
}

Parameters#

generateOpenApi(options) takes an OpenApiOptions object:

Return value#

A promise with the document as a JSON object:

{
  "openapi": "3.1.0",
  "info": { "title": "Store API", "version": "1.4.0" },
  "paths": {
    "/api/users/{id}": {
      "get": {
        "operationId": "users_byId_get",
        "parameters": [{ "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/userSchema" } } } } }
      }
    }
  },
  "components": {
    "schemas": { "userSchema": { "type": "object" } },
    "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-meeko.sid" } }
  }
}

• API. One operation per method, with operationId <clave del cliente con _>_<método>. [id] segments become {id} and their schemas come from params; query provides in: "query" parameters; body provides requestBody; status (200, 201, 202 or 204) provides the response. auth: "required" adds security: [{ sessionCookie: [] }].
• RPC. A POST at its path (/_meeko/rpc/…) with operationId rpc_<id con _>, input as the body and output as the 200 response.

Examples#

The public schema registry#

// shared/schemas/public.ts: only what the document can expose
export { userParams, userSchema } from "./user";
export { orderInput, orderSchema } from "./order";

Private schemas (for an internal webhook, for example) stay outside; if an endpoint uses them, generateOpenApi fails instead of publishing them.

Check the document in CI#

npx tsx scripts/openapi.ts && npx @redocly/cli lint openapi.json
git diff --exit-code openapi.json   # the published contract does not change without review

Common mistakes#

A schema outside the registry#

// server/api/users/[id].get.ts uses userSchema, which is not in publicSchemas
await generateOpenApi({ ...options, publicSchemas: { orderSchema } });

Error: OpenAPI <archivo> response uses a schema outside publicSchemas, with the endpoint file's path (params, query, body, input or output depending on the field).

await generateOpenApi({ ...options, publicSchemas: { orderSchema, userSchema, userParams } });

A catch-all route or non-JSON response#

server/api/files/[...path].get.ts
server/api/report.get.ts with contentType: "response"

Error: OpenAPI cannot represent catch-all route /api/files/[...path] and Error: OpenAPI non-JSON response requires an explicit representation: …. Document these routes manually or leave them out of the manifest you pass.

Routes with [id] segments and JSON responses with schemas

No load#

await generateOpenApi({ manifest, info, publicSchemas, toJsonSchema });

TypeError: OpenAPI generation requires a module loader.

await generateOpenApi({ manifest, info, publicSchemas, toJsonSchema, load: (file) => import(pathToFileURL(file).href) });

A converter that does not return an object#

toJsonSchema: (schema) => JSON.stringify(convert(schema)),

Error: OpenAPI schema userSchema is not representable as JSON Schema. If the converter throws (a transform JSON Schema cannot express), the error is OpenAPI schema userSchema cannot be converted: ….

toJsonSchema: (schema) => toJsonSchema(schema as never), // an object, not a string

Notes#

• Outside the server. Does not run in meeko build or production: call it from a script. It loads handlers, so their imports must resolve in that process.
• Security. The explicit registry guarantees the document only shows what you chose to publish; review the openapi.json diff like any public contract.
• Route parameters. Each [nombre] segment must exist in the params schema (an object with properties); if missing, OpenAPI path parameter id is missing from … params schema.
• Duplicates. Two operations with the same method and path are an error (OpenAPI duplicate operation: GET /api/users).

Related#

• defineApiRouteDeclares a server/api endpoint with public schemas, guards, status and handler; the server validates everything and generates the typed api.* client.
• defineRpcDeclares an RPC procedure in server/rpc with input and output schemas, guards and a handler, called by the application with typed rpc.*.
• discoverServerManifestDescubre de forma estática los endpoints de server/api, los procedimientos de server/rpc y los canales de server/socket, para el build y el desarrollo.
• API and RPCMeeko as a full-stack framework
• Build, deployment and verificationMeeko as a full-stack framework