@ferry-200/gen-server-client

Generate a TypeScript API client from an OpenAPI document.

The package wraps a small OpenAPI client generation pipeline:

1. format and normalize the OpenAPI document with openapi-format
2. optionally rewrite operation IDs from path refs into stable camelCase names
3. generate a TypeScript client with @hey-api/openapi-ts

Install

npm install -D @ferry-200/gen-server-client

The default generated client is @hey-api/client-axios, so projects using the generated code should also install axios:

npm install axios

Usage

Generate from a remote OpenAPI YAML file:

npx gen-server-client \
  --input https://raw.githubusercontent.com/figma/rest-api-spec/refs/heads/main/openapi/openapi.yaml \
  --out src/gen/api-client

Generate from a running server:

npx gen-server-client \
  --input http://localhost:3000/openapi.json \
  --out src/gen/api-client

Local OpenAPI files are also supported:

npx gen-server-client --input ./path/to/spec.yaml --out src/gen/api-client

Options

--input, -i <url-or-file>       OpenAPI URL or local file.
--out, -o <dir>                 Generated TypeScript client output directory.
--cache-dir <dir>               Intermediate OpenAPI file directory.
--client, -c <name>             @hey-api/openapi-ts client.
--operation-id <mode>           path-ref or preserve.
--clean                         Remove output directory before generation.
--help, -h                      Show help.
--version, -v                   Show package version.

Defaults:

--input is required
--out src/gen/api-client
--cache-dir .gen-server-client
--client @hey-api/client-axios
--operation-id path-ref

--operation-id path-ref makes openapi-format generate path-ref operation IDs, then rewrites names such as:

GET::/files/{file_key}

into:

getFileByFileKey

Use --operation-id preserve if the input OpenAPI document already has the operation IDs you want.

Remote Test Fixture

This repository uses the Figma REST API OpenAPI YAML as a remote URL fixture:

npm run gen:test-url

The generated fixture client is written to:

.tmp/figma-client