openapi-typescript

The openapi-typescript project is a suite of tools designed to provide end-to-end type safety for APIs defined by OpenAPI schemas. The ecosystem consists of three primary packages:

• openapi-typescript: A type generator that converts OpenAPI schemas into statically-analyzable, runtime-free TypeScript types. It supports complex schemas, preserves original capitalization, and runs in any Node.js environment using either local files or remote URLs.
• openapi-fetch: A lightweight, performant wrapper around the native Fetch API. It provides strict type inference from OpenAPI schemas with minimal generic boilerplate and reduces common tasks like await res.json().
• openapi-react-query: A wrapper for @tanstack/react-query that provides strict type inference from OpenAPI schemas while reducing boilerplate and respecting the original TanStack APIs.

The swr-openapi package has moved from this monorepo to its own dedicated repository. For the latest version, documentation, and source code, please use the following links:

• NPM Package: swr-openapi
• GitHub Repository: htunnicliff/swr-openapi
• Documentation: swr-openapi Docs

openapi-typescript is designed to convert any valid OpenAPI schema into TypeScript types with the following characteristics:

• Statically-analyzable and runtime-free: The generated types are pure TypeScript and do not add weight to your client-side bundles (with minor exceptions like enums).
• Schema Fidelity: Generated types match your original schema as closely as possible, preserving original capitalization and structures.
• Environment Agnostic: The type generator only requires Node.js to run and does not depend on Java or Python.
• Flexible Schema Sourcing: Supports fetching OpenAPI schemas from local files, local servers, or remote servers.
• No Schema Validation: The tool focuses on type generation rather than validating the schema itself (it is recommended to use tools like Redocly for linting/validation).

To use $api.useQuery, you must first initialize a fetch client using openapi-fetch and then wrap it with createClient from openapi-react-query using your generated OpenAPI types.

import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});

export const $api = createClient(fetchClient);

When working with OpenAPI-derived types, avoid the urge to rename snake_case properties to camelCase to match TypeScript conventions. Preserving the API schema as-written prevents several maintenance issues:

• Avoids manual re-typing of generated types.
• Eliminates the need for runtime renaming, which improves performance.
• Removes the need to build and maintain name transformation utilities.
• Ensures requestBody objects remain compatible with the API without manual transformation.

Several options were removed from the CLI and Node.js API in version 7.0.0. To migrate, use a redocly.yaml configuration file.

• Removed options: --auth, --httpHeaders, --httpMethod, and fetch (Node.js-only).
  • Migration: Specify these in your redocly.yaml under the http setting.
• Renamed flags:
  • --immutable-types $\rightarrow$ --immutable
  • --support-array-length $\rightarrow$ --array-length
• Schema Globbing: Globbing schemas is no longer supported. Use redocly.yaml to specify multiple schemas with their respective outputs.

To test that openapi-fetch is making the correct requests, you can provide a spy function (like vi.fn() from Vitest or jest.fn() from Jest) to the fetch option in the createClient configuration. This allows you to inspect the URL, method, and body of the outgoing request.

import createClient from "openapi-fetch";
import { expect, test, vi } from "vitest";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

test("my request", async () => {
  const mockFetch = vi.fn();
  const client = createClient<paths>({
    baseUrl: "https://my-site.com/api/v1/",
    fetch: mockFetch,
  });

  const reqBody = { name: "test" };
  await client.PUT("/tag", { body: reqBody });

  const req = mockFetch.mock.calls[0][0];
  expect(req.url).toBe("/tag");
  expect(await req.json()).toEqual(reqBody);
});