rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Start from the template. src/app.service.ts and src/main.ts stay as they are.

Install#

Shell
bun add @rhythmjs/openapi @rhythmjs/swagger

Describe 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.

TypeScript
// 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. swaggerModule is a separate router that serves the Swagger UI page at /docs, loading that document. Both are plain routers added with .use(mount(...)); mount them before any catch-all.

TypeScript
// src/app.module.ts
import { defineDocument } from "@rhythmjs/openapi/document";
import { openapiModule } from "@rhythmjs/openapi/module";
import { Rhythm, decorate, mount } from "@rhythmjs/rhythm";
import { swaggerModule } from "@rhythmjs/swagger";
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(swaggerModule.forRoot()))
  .use(mount(appController));

Things to check#

  • GET /openapi.json is the generated document and GET /docs is the Swagger UI page. path and url on swaggerModule.forRoot move the page and point it at another document URL.
  • Swagger UI loads from a CDN (unpkg.com, pinned to an exact version with subresource integrity), 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/swagger README.

The full app, with tests, is examples/swagger-ui, built from the template.