OpenAPI and Scalar

Someone wants to call your API. A partner, a colleague, an agent. This page is how you hand them the whole surface without writing a spec by hand.

It is probably already on

The starters put openApiModule in modules.ts for you. Open yours and check.

import { openApiModule } from "@questpie/openapi";

export default [openApiModule] as const;

Add it if it is missing, then run questpie generate. Codegen has to see the module before its two routes exist.

Point it at your base path

The starters mount the fetch handler at /api. The generator does not know that. It prefixes every documented path with its own basePath, which defaults to /. The scaffolded config/openapi.ts never sets it. So a fresh app documents //posts, not /api/posts.

One line fixes it.

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

export default openApiConfig({
	info: { title: "My API", version: "1.0.0" },
	basePath: "/api",
	scalar: { theme: "purple" },
});

openApiConfig() hands your object straight back. It exists for the types. Codegen discovers the file, and the spec route reads it when it builds the document. If your handler sits at the root, write basePath: "", not "/".

What you get

Two endpoints, under whatever base path your fetch handler uses.

Start the app and open http://localhost:3000/api/docs. Every collection, global and route is listed, each with a try-it panel. The page pulls Scalar from jsDelivr, so it needs network access to render.

What lands in the document

Five sources merge into one file.

Every document also carries four shared component schemas and two security schemes. Generated paths lists each one.

The document is built once

/api/openapi.json builds the document on the first request and caches it for the life of the app instance. It answers with an ETag and a one-hour Cache-Control, and returns 304 when your If-None-Match matches. So a change to config/openapi.ts needs a restart, not just another request.

Listing an endpoint does not open it

Both routes are ordinary QUESTPIE routes with no access rule. Anyone who can reach them can read your whole API shape. That does not make the endpoints callable. Every collection, global and route in the document is still checked against its own access rules when the call arrives.

The two security schemes say how to authenticate. They say nothing about what you are allowed to do.

Where each topic lives

Next

MCP is the other half. OpenAPI describes your API to whoever reads it. MCP hands the same surface to an agent as callable tools.