apigen-ts
TypeScript client generator from OpenAPI schema
Features
- Generates ready to use
ApiClientwith types (usingfetch) - Single output file, minimal third-party code
- Loads schemas from JSON / YAML, locally and remote
- Ability to customize
fetchwith your custom function - Automatic formating with Prettier
- Can parse dates from date-time format (
--parse-datesflag) - Support OpenAPI v2, v3, v3.1
- Can be used with npx as well
Install
yarn install -D apigen-tsUsage
1. Generate
# From url
yarn apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-client.ts
# From file
yarn apigen-ts ./openapi.json ./api-client.tsRun yarn apigen-ts --help for more options. Examples of generated clients here.
2. Import
import { ApiClient } from "./api-client"
const api = new ApiClient({
baseUrl: "https://example.com/api",
headers: { Authorization: "secret-token" },
})3. Use
// GET /pet/{petId}
await api.pet.getPetById(1) // -> Pet
// GET /pet/findByStatus?status=sold
await api.pet.findPetsByStatus({ status: "sold" }) // -> Pets[]
// PUT /user/{username}; second arg body with type User
await api.user.updateUser("username", { firstName: "John" })Advanced
Login flow
const { token } = await api.auth.login({ usename, password })
api.Config.headers = { Authorization: token }
await api.protectedRoute.get() // here authenticatedAutomatic date parsing
yarn apigen-ts ./openapi.json ./api-client.ts --parse-datesconst pet = await api.pet.getPetById(1)
const createdAt: Date = pet.createdAt // date parsed from string with format=date-timeErrors handling
An exception will be thrown for all unsuccessful return codes.
try {
const pet = await api.pet.getPetById(404)
} catch (e) {
console.log(e) // parse error depend of your domain model, e is awaited response.json()
}Also you can define custom function to parse error:
class MyClient extends ApiClient {
async ParseError(rep: Response) {
// do what you want
return { code: "API_ERROR" }
}
}
try {
const api = MyClient()
const pet = await api.pet.getPetById(404)
} catch (e) {
console.log(e) // e is { code: "API_ERROR" }
}Node.js API
Create file like apigen.mjs with content:
import { apigen } from "apigen-ts"
await apigen({
source: "https://petstore3.swagger.io/api/v3/openapi.json",
output: "./api-client.ts",
// everything below is optional
name: "MyApiClient", // default "ApiClient"
parseDates: true, // default false
resolveName(ctx, op, proposal) {
// proposal is [string, string] which represents module.funcName
if (proposal[0] === "users") return // will use default proposal
const [a, b] = op.name.split("/").slice(3, 5) // eg. /api/v1/store/items/search
return [a, `${op.method}_${b}`] // [store, 'get_items'] -> apiClient.store.get_items()
},
})Then run with: node apigen.mjs
Compare
- openapi-typescript-codegen (npm): no single file mode #1263
- openapi-typescript (npm): low level api; no named types export to use in client code
- openapi-generator-cli (npm): wrapper around java lib
- swagger-typescript-api (npm): complicated configuration; user-api breaking changes between versions