Integrations
Scalar
Serve an interactive API reference: the OpenAPI document comes from the routes, and one module renders it with Scalar.
Start from the template. src/app.service.ts and src/main.ts stay as they are.
Install#
bun add @rhythmjs/openapi @rhythmjs/scalarDescribe the route#
apiOperation and apiResponse are ordinary middleware that carry documentation, so the router stays the single source of truth: what is documented is what runs. Wrap the router with documented() right after constructing it, or it is left out of the document.
// src/app.controller.ts
import { documented } from "@rhythmjs/openapi/generate";
import { apiOperation } from "@rhythmjs/openapi/operation";
import { apiResponse } from "@rhythmjs/openapi/response";
import { RhythmRouter } from "@rhythmjs/router";
import type { RhythmHttpContext } from "@rhythmjs/router/context";
import type { appService } from "./app.service";
import { text } from "@rhythmjs/router/response";
export type AppContext = RhythmHttpContext & {
appService: typeof appService;
};
export const appController = documented(new RhythmRouter<AppContext>()).get(
"/",
apiOperation({ summary: "Say hello", operationId: "getHello" }),
apiResponse(200, { description: "A greeting", content: { "text/plain": { schema: { type: "string" } } } }),
(ctx) => {
text(ctx, ctx.appService.getHello());
},
);Mount the two modules#
openapiModule finds the documented routers of the app it is mounted in and serves only the document, at /openapi.json. scalarModule is a separate router that serves the Scalar page at /docs, loading that document. Both are plain routers added with .use(mount(...)); mount them before any catch-all.
// src/app.module.ts
import { defineDocument } from "@rhythmjs/openapi/document";
import { openapiModule } from "@rhythmjs/openapi/module";
import { Rhythm, decorate, mount } from "@rhythmjs/rhythm";
import { scalarModule } from "@rhythmjs/scalar";
import { appController } from "./app.controller";
import { appService } from "./app.service";
const document = defineDocument({ info: { title: "Hello API", version: "1.0.0" } });
export const appModule = new Rhythm({ name: "app" })
.register(decorate(() => ({ appService })))
.use(mount(openapiModule.forRoot({ document })))
.use(mount(scalarModule.forRoot()))
.use(mount(appController));Things to check#
GET /openapi.jsonis the generated document andGET /docsis the Scalar page.pathandurlonscalarModule.forRootmove the page and point it at another document URL.- Scalar loads from a CDN, so the browser needs network access to render the page.
- Neither endpoint has authentication, and the document publishes your route map. Mount them behind your own auth, or only outside production, if the API is not public.
- The options of each package are on the OpenAPI page and in the
@rhythmjs/scalarREADME.
The full app, with tests, is examples/scalar, built from the template.