rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

/body#

TypeScript
function apiBody<TSchema extends StandardSchemaV1>(
  schema: TSchema,
  options?: ApiBodyOptions,
): ExtensionMiddleware<ValidationContext, Validated<"body", TSchema>>;

interface ApiBodyOptions {
  description?: string;
  required?: boolean; // documented; defaults to true
  contentType?: string; // default "application/json"
  example?: unknown;
  examples?: Record<string, ExampleObject | ReferenceObject>;
  encoding?: Record<string, EncodingObject>;
  content?: Record<string, MediaTypeSpec>; // full override
}

Documents the request body and validates it. Extraction follows contentType: JSON parses request.clone().json() (failure: issue "Malformed JSON in request body"), form-data collects entries with repeated keys as arrays, urlencoded parses the text, anything else validates the raw text. This subpath also re-exports the shared validation types: Validated, ValidationContext, ValidationTarget ("body" | "query" | "param" | "header" | "cookie"), ValidationIssue, and ValidationFailure, the 400 body { success: false, target, issues }.

/query, /param, /header, /cookie#

TypeScript
function apiQuery<TSchema>(schema, options?: { overrides? }): ExtensionMiddleware<..., Validated<"query", TSchema>>;
function apiParam<TSchema>(schema, options?: { overrides? }): ExtensionMiddleware<..., Validated<"param", TSchema>>;
function apiHeader<TSchema>(schema, options?: { overrides? }): ExtensionMiddleware<..., Validated<"header", TSchema>>;
function apiCookie<TSchema>(schema, options?: { overrides? }): ExtensionMiddleware<..., Validated<"cookie", TSchema>>;

Each documents one parameter group (in: query, path, header, or cookie) and validates the corresponding request part: query params with repeated keys collected as arrays, router ctx.params, all request headers as a lowercase record, or parsed cookies. The generator expands the object schema's properties into individual OpenAPI parameters; required from the schema (path parameters are always required), with per-property overrides (ParameterOverride: description, required, deprecated, style, explode, example, and so on).

/operation and /tags#

TypeScript
function apiOperation(options: ApiOperationOptions): Middleware<RhythmHttpContext>;
// summary, description, operationId, deprecated, externalDocs, servers

function apiTags(...tags: string[]): Middleware<RhythmHttpContext>;

Doc-only fragments. apiOperation merges its fields onto the operation; later fragments overwrite earlier ones. apiTags appends tags, de-duplicated across inherited and route-level fragments.

/response#

TypeScript
type ResponseStatus = number | "default" | "1XX" | "2XX" | "3XX" | "4XX" | "5XX";

function apiResponse(status: ResponseStatus, options: ApiResponseOptions): Middleware<RhythmHttpContext>;

interface ApiResponseOptions {
  description: string; // required by OpenAPI
  schema?: SchemaLike; // shorthand for content[contentType].schema
  contentType?: string; // default "application/json"
  example?: unknown;
  examples?: Record<string, ExampleObject | ReferenceObject>;
  content?: Record<string, MediaTypeSpec>; // full override
  headers?: Record<string, HeaderSpec | ReferenceObject>;
  links?: Record<string, LinkObject | ReferenceObject>;
}

One response per call; stack several for several statuses. Response schemas resolve with the schema's output type (request schemas use the input type), so zod transforms document what the client actually receives. When no route declares any response, the generator emits a default 200 Successful response.

/security#

TypeScript
function apiSecurity(name: string, scopes?: string[]): Middleware;
function apiBearerAuth(name = "bearer"): Middleware;
function apiBasicAuth(name = "basic"): Middleware;
function apiCookieAuth(name = "cookie"): Middleware;
function apiKeyAuth(name = "api-key"): Middleware;
function apiOAuth2(scopes: string[], name = "oauth2"): Middleware;
function apiNoSecurity(): Middleware;

Security requirements referencing the scheme names declared in the document config's securitySchemes. Requirements accumulate and de-duplicate across fragments; apiNoSecurity() resets them and emits security: [], opting the route out of document-level defaults; a later requirement turns security back on.

/exclude, /extension, /callback#

TypeScript
function apiExclude(): Middleware; // route disappears from the document
function apiExtension(name: `x-${string}`, value: unknown): Middleware; // throws unless name starts with "x-"
function apiCallback(name: string, callback: CallbackObject | ReferenceObject): Middleware;

/document#

TypeScript
function defineDocument(config: OpenAPIConfig): OpenAPIConfig;

interface OpenAPIConfig {
  info: InfoObject; // required: title, version
  jsonSchemaDialect?: string;
  servers?: ServerObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocsObject;
  security?: SecurityRequirementObject[]; // document-wide default
  securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
  components?: ComponentsObject;
  webhooks?: Record<string, PathItemObject>;
  extensions?: Record<`x-${string}`, unknown>;
}

defineDocument is an identity function that exists for inference and autocompletion; the config object is the document-level half of the generated file. securitySchemes is a convenience that merges into components.securitySchemes.

/generate#

TypeScript
function documented<R extends object>(router: R): R & RouterSource;

function generate(
  routers: RouterSource | readonly RouterSource[],
  config: OpenAPIConfig,
  options?: GenerateOptions,
): Promise<OpenAPIObject>;

interface RouterSource {
  readonly entries: ReadonlyArray<
    | { kind: "middleware"; fn: unknown }
    | { kind: "route"; method: string; path: string; handlers: readonly unknown[] }
  >;
}

interface GenerateOptions {
  openapi?: string; // document version string, default "3.1.2"
  includeUndocumented?: boolean; // default false
}

documented(router) wraps use(), get, post, put, patch and delete on the router so it records them, and returns the same router (typed also as RouterSource). Call it right after construction; a router that is not wrapped, or wrapped after routes were added, is silently left out of the document. Wrapping twice is harmless.

generate walks the entries in order. A middleware entry carrying a fragment joins the inherited list applied to every route after it; each route merges inherited then own fragments. Routes with no fragment of their own are dropped unless includeUndocumented is set. Paths convert :param to {param} and * to {wildcard}. Schemas resolve through the resolver, and emitted $defs are hoisted into components.schemas; identical definitions share a name, conflicting ones get numeric suffixes, and $refs are rewritten to #/components/schemas/…. Given an array of routers it merges their paths, keeping each router's inherited middleware to its own routes. Only get, post, put, patch and delete operations are documented.

/module#

TypeScript
const openapiModule: { forRoot(options: OpenapiOptions): RhythmRouter & { openapiService: OpenapiService } };
interface OpenapiOptions extends GenerateOptions {
  document: OpenAPIConfig;
  path?: string; // where the document is served, default "/openapi.json"
}
interface OpenapiService {
  document(): Promise<OpenAPIObject>;
}

A plain RhythmRouter (named openapi) with one GET route on path, added to an app with .use(mount(module)). It documents the app it is mounted in: on the first request it scans that app's sources, including nested routers and apps, for documented() routers and generates one document from all of them. Each router's use() middleware stays scoped to that router. Generation is lazy, so routers mounted after the module are still found, and the result is cached; a failed generation is evicted so the next request retries. A module never mounted in an app fails on the first request. openapiService.document() resolves to the same document in code. Only an exact GET on path is answered; mount() calls next() afterwards, so other requests fall through. Reference UIs live in @rhythmjs/scalar and @rhythmjs/swagger.

/metadata#

TypeScript
const OPENAPI_METADATA: symbol; // Symbol.for("rhythmjs.openapi")

function withFragment<TFn>(fn: TFn, fragment: OperationFragment): TFn;
function fragmentOf(fn: unknown): OperationFragment | undefined;
function docOnly(fragment: OperationFragment): Middleware<RhythmHttpContext>;

The extension seam for writing custom api* helpers. withFragment attaches a fragment to any function under the shared symbol; fragmentOf reads it back (the generator uses it); docOnly wraps a fragment in a pass-through middleware. OperationFragment holds the mergeable slices (operation, tags, parameters (ParameterGroupSpec), requestBody (RequestBodySpec), responses (ResponseSpec), security (or "none"), callbacks, extensions, and exclude) alongside the spec types SchemaLike (Standard Schema or raw SchemaObject), MediaTypeSpec, HeaderSpec, and ParameterOverride.

/resolver#

TypeScript
type SchemaIO = "input" | "output";
function isStandardSchema(value: unknown): value is StandardSchemaV1;
function resolveSchema(schema: SchemaLike, io: SchemaIO): SchemaObject;

Converts a SchemaLike to JSON Schema (draft 2020-12). Raw objects pass through; Standard Schemas must implement the Standard JSON Schema interface (~standard.jsonSchema, zod 4.2+) or resolveSchema throws with a message naming the vendor. Types JSON Schema cannot express (File, Date, …) resolve to {} instead of throwing; a $schema dialect field is stripped.

/types#

The complete OpenAPI 3.1 object model as TypeScript interfaces, all supporting x- extension fields: OpenAPIObject, InfoObject, ContactObject, LicenseObject, ServerObject, ServerVariableObject, PathsObject, PathItemObject, OperationObject, ParameterObject (ParameterLocation, ParameterStyle), HeaderObject, RequestBodyObject, MediaTypeObject, EncodingObject, ResponseObject, ResponsesObject, ExampleObject, LinkObject, CallbackObject, TagObject, ExternalDocsObject, ReferenceObject, SchemaObject (a raw JSON Schema record or boolean), ComponentsObject, SecuritySchemeObject (apiKey, http, mutualTLS, oauth2 with OAuthFlowsObject/OAuthFlowObject, openIdConnect), and SecurityRequirementObject.