OpenAPI
Auto-generate OpenAPI 3.1 spec and interactive API docs from your schema.
QUESTPIE auto-generates an OpenAPI 3.1 spec from your collections, globals, and routes at runtime. The spec is served as a standard route alongside interactive Scalar API docs.
Setup
Install the OpenAPI package:
bun add @questpie/openapiRegister the module in your modules.ts:
import { adminModule } from "@questpie/admin/server";
import { openApiModule } from "@questpie/openapi";
export default [
adminModule,
openApiModule({
info: {
title: "My API",
version: "1.0.0",
},
}),
] as const;Run codegen to pick up the new module:
bunx questpie generateThe module registers two routes:
| Route | Description |
|---|---|
GET /api/openapi.json | OpenAPI 3.1 JSON spec |
GET /api/docs | Scalar interactive API reference |
Configuration
openApiModule({
// OpenAPI info block
info: {
title: "My API",
version: "1.0.0",
description: "Backend for my app",
},
// Server definitions
servers: [{ url: "https://api.example.com", description: "Production" }],
// Base path (must match your adapter's basePath)
basePath: "/api",
// Exclude specific collections or globals from the spec
exclude: {
collections: ["_internal_logs"],
globals: ["_cache"],
},
// Include auth endpoints (sign-in, sign-up, etc.)
auth: true,
// Include search endpoints
search: true,
// Scalar UI theme
scalar: {
theme: "purple",
},
// Custom route keys (defaults shown)
specPath: "openapi.json",
docsPath: "docs",
});What Gets Documented
The spec is generated at runtime from your app's schema:
| Source | Documented As |
|---|---|
| Collections | CRUD endpoints (GET /collections/{name}, POST, PUT, DELETE) |
| Globals | Read/update endpoints (GET /globals/{name}, PUT) |
| Routes | App routes (/api/{path}) with input/output schemas when available |
| Auth | Sign-in, sign-up, session endpoints (when auth: true) |
| Search | Search endpoints (when search: true) |
Collection and global field schemas (from Zod) are automatically converted to JSON Schema in the spec. Route input/output schemas are included when defined.
Manual Route Approach
Instead of the module, you can create route files directly:
import { openApiRoute } from "@questpie/openapi";
export default openApiRoute({
info: { title: "My API", version: "1.0.0" },
});import { docsRoute } from "@questpie/openapi";
export default docsRoute({
scalar: { theme: "purple" },
});This gives you full control over the route paths and allows co-locating OpenAPI config with other route files.
Programmatic Access
Generate the spec object directly for custom use cases:
import { generateOpenApiSpec } from "@questpie/openapi";
const spec = generateOpenApiSpec(app, {
info: { title: "My API", version: "1.0.0" },
});
// Use spec object for testing, CI validation, etc.Related Pages
- Routes — Typed JSON route handlers
- Routes (Raw) — Raw HTTP route handlers
- Modules — Module system