Typed client from OpenAPI

This guide gives the API’s consumers — a frontend, another service — a client with typed paths, parameters, bodies and errors. It is generated from the OpenAPI document that Tetsu builds from your routes.

Tetsu has no RPC client that imports the server’s types, as Elysia’s Eden or Hono’s client do. The document is the boundary instead: a client in another repository or another language reads it without the server’s code, and a change to the API shows up as a diff of one file. The cost is one generation step.

Serving the document

Mount docs() next to your controllers, and the application serves its document at /openapi.json:

import { controller, createApp, httpError, route } from "@tetsujs/core";
import { docs } from "@tetsujs/openapi";

const usersController = controller("Users", () => ({
  get: route({
    method: "GET",
    path: "/users/:id",
    schema: {
      params: z.object({ id: z.coerce.number() }),
      response: { 200: User, 404: UserNotFound },
    },
    handler: (ctx) => {
      if (ctx.params.id !== 1) throw httpError(404, "USER_NOT_FOUND");

      return { id: 1, name: "Ada" };
    },
  }),
}));

export const app = createApp({
  routes: [usersController(), docs({ info: { title: "Users API", version: "1.0.0" }, ui: false })],
});

ui: false serves only the document; leave it out to also get a documentation page at /docs.

Generating the types

openapi-typescript turns the document into TypeScript types, from a file or from a URL:

bunx openapi-typescript http://localhost:3000/openapi.json -o src/api.d.ts

The output is types only, with a paths interface keyed by the document’s paths. It costs nothing at runtime.

Calling the API

openapi-fetch is a thin fetch wrapper typed by that paths interface:

import createClient from "openapi-fetch";
import type { paths } from "./api";

const api = createClient<paths>({ baseUrl: "https://api.example.com" });

const { data, error } = await api.GET("/users/{id}", {
  params: { path: { id: 42 } },
});

if (error) {
  const code = error.error;
const code: "INTERNAL_SERVER_ERROR" | "USER_NOT_FOUND" | "VALIDATION_FAILED"
  console.log(code);
} else {
  console.log(data.name);
}

The path is checked against the document, id must be a number, and data is the 200 body. A wrong path or a missing parameter is a compile error.

Errors are in the document

error is the body of any other status, typed as the union of what the document lists for the operation. That includes the failures the framework answers by itself, such as 422 for a validation failure and 500. Branch on the error code, not on the message, which is written for people and may change. See Errors.

An error that is thrown but not declared is not in the document. A route lists its own in its response map, as 404 above. A hook that refuses describes its refusal with documented() or secured(). A custom error format is described with errors.

Operation ids

A generator that writes a function per operation names it after the operationId. Tetsu builds it from the controller’s name and the route’s field: get in controller("Users", …) is usersGet. Renaming the controller renames the functions, so on a public API state the id on each route with docs: { operationId }. Two routes with the same id are an error when the document is built. See Operation ids.

An SDK instead

@hey-api/openapi-ts generates the types and a function per operation:

bunx @hey-api/openapi-ts -i http://localhost:3000/openapi.json -o src/client

openapi-fetch keeps calls in the shape of HTTP; an SDK hides them behind functions. Which to use is a matter of taste.

Where the client lives

The client belongs to its consumers: the frontend’s repository, or a package of its own in a monorepo. The server only hands over the document, either served, as above, or written to a file and committed. A committed file makes every API change a visible diff and allows the CI check below.

openapi() builds the document without serving it. The script imports the application, not main.ts, so nothing starts listening:

scripts/openapi.ts

import { openapi } from "@tetsujs/openapi";
import { app } from "../src/app";

const { document, warnings } = openapi(app, { info: { title: "Users API", version: "1.0.0" } });

for (const warning of warnings) console.error(`${warning.route}: ${warning.message}`);

if (warnings.length > 0) process.exit(1);

await Bun.write("openapi.json", `${JSON.stringify(document, null, 2)}\n`);

A warning means part of a route could not be described, most often a schema from a validator that emits no JSON Schema. The script fails rather than write an incomplete document. Keeping the application apart from main.ts is the layout Structuring an application describes.

Checking the document in CI

With the document committed, CI regenerates it and fails when it differs from the committed file:

bun scripts/openapi.ts
git diff --exit-code openapi.json

A pull request that changes the API without updating the document fails, and one that updates it shows the contract change next to the code. A tool such as oasdiff can list which changes break existing clients.

To check the other direction, that real responses match the document, use assertDescribed in tests.