OpenAPI and Scalar

The @questpie/openapi module turns your running app into self-documenting API. Register one module and QUESTPIE introspects everything it already knows, your collections, globals, routes, auth endpoints, and search, and emits a complete OpenAPI 3.1 spec at GET /api/openapi.json, plus an interactive Scalar API reference at GET /api/docs. No decorators, no hand-written spec, no separate build step: the spec is generated from the same runtime metadata that powers your typed client and admin panel.

What it does

• One module, a documented API. Add openApiModule to modules.ts and you get two routes for free: a JSON spec and a hosted Scalar UI.
• Generated from runtime metadata. Collections become CRUD paths, globals become get/update paths, your routes become operations with Zod-derived request/response schemas, and Better Auth + search endpoints are included.
• Interactive docs out of the box. Scalar renders the spec into a browsable, try-it reference at /api/docs, themeable, with code samples.
• Typed, declarative config. Set the title, version, servers, and Scalar theme in config/openapi.ts with openApiConfig(), full type inference, discovered by codegen.
• Cacheable spec. The JSON spec is generated once per app instance and served with an ETag and Cache-Control, so repeat fetches are cheap.

Quick start

Add the module to your modules.ts. Modules are auto-wired, there is nothing imperative to register.

import { adminModule } from "@questpie/admin/modules/admin";
import { openApiModule } from "@questpie/openapi/server";

export default [adminModule, openApiModule] as const;

Re-run codegen so the new module's routes are discovered, then start the app:

questpie generate

That is all. With the scaffold's HTTP basePath of /api (the framework default is /, see Gotchas), two endpoints are now live:

GET /api/openapi.json   → OpenAPI 3.1 JSON spec
GET /api/docs           → Scalar interactive API reference

Open http://localhost:3000/api/docs and you have a browsable reference for your entire API.

Configuration

Set the spec metadata and Scalar options in config/openapi.ts. Codegen discovers this file (via the module's bundled codegen plugin) and the module reads it at request time, you never pass config imperatively.

import { openApiConfig } from "@questpie/openapi/server";

export default openApiConfig({
  info: {
    title: "My API",
    version: "1.0.0",
    description: "Public API for my app.",
  },
  servers: [{ url: "https://api.example.com", description: "Production" }],
  basePath: "/api",
  scalar: { theme: "purple" },
});

openApiConfig() is an identity factory, it returns its argument unchanged and exists purely for type inference.

OpenApiModuleConfig

The config object accepts every field below. All are optional; the defaults produce a working spec for an unconfigured app.

ScalarConfig

Options passed straight through to the Scalar API reference.

The Scalar UI is a tiny HTML page that inlines the generated spec as JSON and loads @scalar/api-reference from a CDN.

What gets documented

Internally, generateOpenApiSpec(app, routes, config) walks the app's runtime metadata and merges five sources into one spec.

Every spec also includes shared component schemas (ErrorResponse, SuccessResponse, CountResponse, DeleteManyResponse) and two security schemes, bearerAuth (HTTP bearer) and cookieAuth (the better-auth.session_token cookie).

How a route projects into the spec

For each route in the tree, the generator builds the OpenAPI path from the file-convention key, literal segments are kebab-cased and [param] / [...slug] become {param} / {slug} templates, matching the URLs the HTTP adapter actually serves:

import { route } from "questpie";
import { z } from "zod";

export default route()
  .get()
  .schema(z.object({ format: z.enum(["json", "csv"]) }))
  .outputSchema(z.object({ revenue: z.number(), year: z.number() }))
  .handler(async ({ input, params }) => ({
    revenue: 42_000,
    year: Number(params.year),
  }));

projects to roughly:

{
  "/api/reports/{year}": {
    "get": {
      "operationId": "route_reports_[year]",
      "summary": "reports/[year]",
      "tags": ["Routes: reports"],
      "parameters": [
        { "name": "year", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "requestBody": {
        "required": true,
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/route_reports_[year]_Input" } } }
      },
      "responses": {
        "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/route_reports_[year]_Output" } } } }
      }
    }
  }
}

A route that serves multiple methods (.get().post()) emits one operation per method on the same path, each with a method-suffixed operationId. Raw routes (no input schema) document a permissive request body (application/json or application/octet-stream) and a generic 200 response.

Schema conversion caveat

Route input/output schemas are converted with Zod's z.toJSONSchema. When a schema can't be converted, most commonly because it contains a transform or refinement, the generator catches the error and falls back to a permissive { "type": "object", "description": "Schema could not be generated" }. Plain object/primitive schemas convert faithfully. Improving this fidelity is part of the hardening effort.

Custom mounting and standalone generation

The module is a thin wrapper over two exported route factories. Drop either into your own routes/ directory if you want a different path or want to apply your own access rule:

import { openApiRoute } from "@questpie/openapi/server";

// Serves the OpenAPI 3.1 JSON (cached with ETag).
export default openApiRoute();

import { docsRoute } from "@questpie/openapi/server";

// Serves the Scalar UI.
export default docsRoute();

Both factories read config from config/openapi.ts at request time, or take an explicit config argument that overrides it.

To generate the spec without mounting any route, for a build step, a snapshot test, or a client generator, call generateOpenApiSpec directly:

import { generateOpenApiSpec } from "@questpie/openapi/server";
import { app } from "#questpie";

const spec = generateOpenApiSpec(app, {
  basePath: "/api",
  info: { title: "My API", version: "1.0.0" },
});
// spec.openapi === "3.1.0"; routes are read from app.config.routes automatically.

Access control

The spec and docs routes are ordinary QUESTPIE routes, so they are public by default, anyone who can reach /api/docs and /api/openapi.json can read your full API shape. This mirrors how all routes behave: public unless you add an .access() rule.

To restrict who can see the docs, mount the factories yourself (see Custom mounting) and add an access rule, but note that openApiRoute() / docsRoute() return a finished raw route definition, so you wrap them at a higher level (e.g. gate the path in your HTTP layer or a reverse proxy) rather than chaining .access() onto the factory result. Most teams leave the spec public and protect the endpoints it documents via each collection's and route's own access rules, the spec describes the surface; access control governs who can actually call it.

Gotchas

• basePath mismatch produces wrong URLs. The generator prepends config.basePath (default /) to every path. If your fetch handler mounts at /api but you leave basePath unset, every documented URL is missing the /api prefix. Set them to the same value.
• specPath / docsPath do nothing today, the routes are fixed at openapi.json and docs. Mount the factories yourself for a custom path.
• Transforms/refinements degrade route schemas to a permissive object, see the schema conversion caveat.
• Security is spec-wide, not per-operation, every path inherits the root security (bearer or cookie); the generator does not emit per-operation security yet.
• Re-run questpie generate after adding the module so its routes are discovered, just like any other route or module. Editing a route body needs no regen; adding/removing route files does.

TypeScript

Types and factories are exported from @questpie/openapi/server (re-exported from the package root):

import {
  openApiConfig,
  generateOpenApiSpec,
  openApiRoute,
  docsRoute,
  openApiModule,
} from "@questpie/openapi/server";

import type {
  OpenApiConfig,
  OpenApiModuleConfig,
  OpenApiSpec,
  ScalarConfig,
} from "@questpie/openapi/server";

The codegen plugin (which discovers config/openapi.ts and emits an AppRouteKeys type) is exported separately as openApiPlugin from @questpie/openapi/plugin; you only need it if you wire the plugin manually instead of using openApiModule (the module bundles it).

Related

• Routes, how route() definitions, .schema()/.outputSchema(), and .meta() produce the operations the spec documents.
• Collections, the CRUD surface that becomes per-collection paths and component schemas.
• Configuration, registering openApiModule in modules.ts and how the fetch handler's basePath is wired.
• Access control, gating the endpoints the spec describes.
• Getting started, scaffold an app, then open /api/docs.