swagger-typescript-api: generating a typed Fetch or Axios client from an OpenAPI spec

What swagger-typescript-api actually produces

The package answers a narrow question: given an OpenAPI Specification, what does the TypeScript client that talks to that API look like? It reads OpenAPI 3.0 and 2.0 documents, in either JSON or YAML, and emits a TypeScript module containing the request methods and the types those methods use. The README states the two output targets plainly: Fetch or Axios. That choice is not cosmetic. It decides whether the generated file depends on a separate HTTP library at runtime or calls the platform's own fetch.

The intended user is an application developer whose backend already publishes a spec. If the spec is current, the generated client is current, and the drift between the documented endpoint and the called endpoint disappears at the point where it is cheapest to fix. The project is not a mock server, not a schema validator at runtime, and not a type-only generator. It writes executable request code.

That last point is the dividing line. Many teams reach for a generator because they want autocomplete on response shapes. swagger-typescript-api gives them that, but it also gives them a client object with methods, which means the generated file becomes part of the runtime surface of the application and has to be reviewed like any other code.

The pipeline: spec in, parsed schema, templated TypeScript out

The repository layout shows the mechanism clearly. There is a src/ directory for the generator logic, a templates/ directory that ships inside the published package (the package.json files array lists dist and templates), and a tests/ directory the README points to for examples. The dependency list confirms the stages: @apidevtools/swagger-parser for parsing and validating the document, swagger2openapi for converting 2.0 input into the 3.0 shape the generator works against, eta as the template engine, and typescript itself as a dependency rather than only a dev dependency.

The template directory being published alongside the compiled output is the design decision that matters most. It means the emitted code is not hard-coded in the generator; it is rendered from templates that a user can replace. The README's media section links an article specifically about using custom templates and configs, which is consistent with that layout. In practice this is the escape hatch for teams whose style guide rejects the default output, and it is also the reason an upgrade can change generated files even when the spec has not changed.

Note the dependency on typescript in the runtime dependency list. Generation is not a pure string operation here; the tool has TypeScript available to it, and the presence of @biomejs/js-api and @biomejs/wasm-nodejs suggests formatting or linting of the output is part of the build. A generated file that has been formatted by a toolchain is easier to diff in review, which is a real benefit when the client is committed to the repository.

Installing swagger-typescript-api and generating a first client

The README gives two entry points. The fastest is npx, which downloads and runs the CLI without adding anything to the project. The command takes the path to the specification with the --path flag and writes the client into the working directory.

npx swagger-typescript-api generate --path ./swagger.json

After it finishes, the working directory contains the generated TypeScript file. Open it and you should see the exported client and the request methods derived from the paths in the spec.

For a project that will regenerate the client repeatedly, install it as a development dependency and invoke the CLI through npx again. The README shows the local install followed by the same generate command.

npm install --save-dev swagger-typescript-api
npx swagger-typescript-api generate --path ./swagger.json

The package also exposes two binaries, sta and swagger-typescript-api, both pointing at dist/cli.mjs, so either name works from a package.json script.

If the client has to be produced from a build script rather than a shell, the library entry point is generateApi. The README's example resolves the spec path from the current working directory and passes it as input.

import * as path from "node:path";
import * as process from "node:process";
import { generateApi } from "swagger-typescript-api";

await generateApi({ input: path.resolve(process.cwd(), "./swagger.json") });

The README defers the rest of the configuration to the documentation, so treat the flags above as the starting point and check the docs before assuming a flag exists.

Where the generated client stops being the right answer

The clearest limitation is the one stated by the project's own description: it generates a client for Fetch or Axios. If your codebase standardizes on a different HTTP layer, or if you have already wrapped fetch in your own request function with interceptors, retries, and auth refresh, the generated client is a second request path you now have to keep consistent with the first. Teams in that position often end up discarding the generated methods and keeping only the types, which is the point at which a type-only generator would have been the smaller dependency.

The second limitation is the input. The tool reads an OpenAPI Specification. If your API is described in code, for example by a framework that derives a schema from route definitions, you need an export step before this tool has anything to work with, and that export has to be trustworthy.

The third is regeneration noise. Because output is rendered from templates, a version bump can change generated files without any change to the spec. The changelog and the .changeset directory exist precisely because releases happen often; the most recent release listed is v13.13.0. Committing the generated client means every upgrade is a review of a potentially large diff, and the templates directory is the only lever you have over how large that diff gets.

Finally, the README does not document a rollback path for a generated client that turns out to be wrong. There is no stated mechanism for pinning the generator's output to a previous shape beyond pinning the package version, which is a normal npm practice rather than a feature of this tool.

openapi-typescript and the type-only alternative

The comparison that comes up most often is with openapi-typescript, and the difference is architectural rather than a matter of quality. openapi-typescript generates type declarations from a schema so that you can annotate the fetch calls you write yourself. swagger-typescript-api generates the calls too. One tool produces a contract; the other produces a contract and an implementation of the client side of it.

That distinction decides the choice. If your team wants full control over request construction, error handling, and the shape of the client object, a type-only generator leaves those decisions where they belong and adds nothing to the runtime bundle. If your team would rather not hand-write forty endpoint wrappers that all do the same thing, swagger-typescript-api removes that work, at the cost of accepting its generated structure and reviewing it on each regeneration.

There is a middle position worth naming: use swagger-typescript-api and replace the templates so the emitted methods call your own request helper. The templates directory ships in the package for exactly this kind of customization, and the linked article on custom templates and configs is the entry point. That path keeps the generation step but lets the output conform to an existing client, which is usually less disruptive than adopting a generated client wholesale.

Maintenance, licensing, and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-18, the same day as the v13.13.0 release. Releases are not rare: v13.12.5, v13.12.6, and v13.13.0 all landed within roughly two months of each other. Frequent releases are good for fixes and bad for anyone who pins the generator and then has to read a changelog before moving. The CHANGELOG.md file at the repository root and the .changeset directory are the two places to look before bumping.

The licence is MIT, stated in both the README and the package.json license field. MIT permits use, modification, and redistribution with the licence and copyright notice retained. Generated output is a separate question from the tool's licence, and the project does not state a position on it, so if your organization treats generated code as a derivative work, that is a question for your own counsel rather than something the README settles.

Upgrade cost has two components. The first is the generator itself, which is a dev dependency and therefore not shipped to users. The second is the generated file, which is shipped if you commit it. Pinning the version in package.json controls the first; the templates directory controls how much the second moves. A team that has not customized templates should expect the generated diff to be driven entirely by upstream template changes.

Editorial conclusion

Adopt swagger-typescript-api when you want generated request methods, not just generated types, and when an OpenAPI 3.0 or 2.0 document is the source of truth for your HTTP layer. Do not adopt it if you only need compile-time types over hand-written fetch calls, or if your schema is defined in code rather than in a spec file. Before committing, verify three things against your own spec: that the generator parses it without validation errors, that the emitted client matches the HTTP client you already use, and that the templates directory gives you enough control over the output to survive a regeneration diff.

Frequently asked questions

Official sources

1. acacode/swagger-typescript-api on GitHub
2. License: MIT
3. Project website
4. README
5. Releases