OpenAPI 3.1 & Interactive Documentation

Brick-TS automatically generates compliant OpenAPI 3.1 JSON specifications from TypeBox schemas and serves interactive documentation via Scalar and Swagger UI.

Minimal ExampleCopy Anchor Link

Enable automatic documentation generation by passing services into brick(). Export the app as the default export so the CLI generators can import the definition without starting a server:

import { brick, defineService, t } from "@brickkit/core";

const usersService = defineService("users");

usersService.action({
  name: "getUser",
  description: "Fetch user profile by ID",
  method: "GET",
  path: "/api/users/:id",
  input: t.Object({ id: t.String() }),
  output: t.Object({ id: t.String(), name: t.String() }),
  execute: ({ input }) => ({ id: input.id, name: "Ada Lovelace" }),
});

export default brick({
  services: [usersService],
  title: "Users API",
  version: "1.0.0",
  description: "User management and profile service mesh",
  prefix: "/api",
});

Start the server from a separate entry file, so importing the app has no side effects:

import app from "./server";

app.listen(4000);

Once started, the following endpoints are available (mounted at the app root, not under prefix):

• OpenAPI 3.1 Spec: http://localhost:4000/openapi.json
• Scalar Modern UI: http://localhost:4000/docs
• Swagger UI: http://localhost:4000/swagger

Server Documentation OptionsCopy Anchor Link

Configure OpenAPI and documentation routes in CreateServerOptions:

Mounting a Dedicated /reference RouteCopy Anchor Link

For web apps that use /docs for product documentation (such as a documentation website), mount the API reference on /reference:

export default brick({
  services: [usersService],
  docs: true,
  reference: {
    path: "/reference",
    title: "Platform API Reference",
  },
});

Adding Documents to the DashboardCopy Anchor Link

brick dev renders API documentation in its dashboard, in the APIs tab, so a page does not have to be served at all. reference.documents adds OpenAPI documents next to the app's own, such as the one Better Auth generates:

export default brick({
  services: [usersService],
  reference: {
    documents: [
      { title: "Auth", document: () => auth.api.generateOpenAPISchema() },
    ],
  },
});

Each entry has a title and a document: an OpenAPI object, or a function (sync or async) that returns one and runs each time the app starts. A document that throws is skipped with a warning. app.referenceDocuments() returns the app's document followed by these, and the app's own is left out when docs is false. With reference: { path } the same options also serve a standalone Scalar page.

Programmatic Spec Generation (generateOpenApiSpec)Copy Anchor Link

Generate specifications programmatically (e.g. for CI pipelines or static documentation sites) without starting an HTTP server:

import { generateOpenApiSpec } from "@brickkit/core";
import { usersService } from "../src/services/users";

const spec = generateOpenApiSpec({
  title: "Production Platform API",
  version: "2.0.0",
  prefix: "/api",
  services: [usersService],
});

await Bun.write("dist/openapi.json", JSON.stringify(spec, null, 2));
console.log("OpenAPI 3.1 spec written to dist/openapi.json");

You can also use the CLI generator, which imports the entry's default export (so it reads the app definition without calling listen()):

bunx brick gen openapi src/server.ts --output openapi.json

Security Requirements in OpenAPICopy Anchor Link

Brick automatically flags protected operations in the OpenAPI specification:

• Actions with authorize guards advertise authentication requirements in their operation definition.
• CRUD resources with access !== "public" automatically advertise security requirements while public CRUD resources omit them.