[](https://openapi-zod-client.vercel.app/)
npm install openapi-zod-client
Generates a zodios (_typescript http client with zod validation_) from a (json/yaml) OpenAPI spec (or just use the generated schemas/endpoints/etc !)
- can be used programmatically _(do w/e you want with the computed schemas/endpoints)_
- or used as a CLI _(generates a prettier .ts file with deduplicated variables when pointing to the same schema/$ref)_
- client typesafety using zodios
- tested (using vitest) against official OpenAPI specs samples
sometimes you don't have control on your API, maybe you need to consume APIs from other teams (who might each use a different language/framework), you only have their Open API spec as source of truth, then this might help 😇
you could use openapi-zod-client to automate the API integration part (doesn't matter if you consume it in your front or back-end, zodios is agnostic) on your CI and just import the generated api client
please just use tRPC or alternatives (zodios is actually a full-featured solution and not just an api client, ts-rest looks cool as well) if you do have control on your API/back-end
with local install:
- pnpm i -D openapi-zod-client
- pnpm openapi-zod-client "./input/file.json" -o "./output/client.ts"
or directly (no install)
- pnpx openapi-zod-client "./input/file.yaml" -o "./output/client.ts"
https://paka.dev/npm/openapi-zod-client
``sh
openapi-zod-client/1.4.2
Usage:
$ openapi-zod-client
Commands:
path/url to OpenAPI/Swagger document as json/yaml
For more info, run any command with the --help flag:
$ openapi-zod-client --help
Options:
-o, --output )#/components/schemas
-t, --template
-p, --prettier
-b, --base-url
-a, --with-alias With alias as api client methods
--error-expr
--success-expr
--media-type-expr
--export-schemas When true, will export all required
--implicit-required When true, will make all properties of an object required by default (rather than the current opposite), unless an explicitly array is set<
--with-deprecated when true, will keep deprecated endpoints in the api output
--group-strategy groups endpoints by a given strategy, possible values are: 'none' | 'tag' | 'method' | 'tag-file' | 'method-file'
--complexity-threshold schema complexity threshold to determine which one (using less than operator) should be assigned to a variableauto-correct
--default-status when defined as , will automatically use default as fallback for response when no status code was declared`
-v, --version Display version number
-h, --help Display this message
You can pass a custom handlebars template and/or a custom prettier config with something like:
pnpm openapi-zod-client ./example/petstore.yaml -o ./example/petstore-schemas.ts -t ./example/schemas-only.hbs -p ./example/prettier-custom.json --export-schemas, there is an example of the output here
- --success-expr is bound to isMainResponseStatus--error-expr
- is bound to isErrorStatus
You can pass an expression that will be safely evaluted (thanks to whence) and works like validateStatus from axios to determine which OpenAPI ResponseItem should be picked as the main one for the ZodiosEndpoint["response"] and which ones will be added to the ZodiosEndpoint["errors"] array.
Exemple: --success-expr "status >= 200 && status < 300"
- You can omit the -o (output path) argument if you want and it will default to the input path with a .ts extension: pnpm openapi-zod-client ./input.yaml will generate a ./input.yaml.ts filepnpx openapi-zod-client https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml -o ./petstore.ts
- Since internally we're using swagger-parser, you should be able to use an URL as input like this:
- Also, multiple-files-documents ($ref pointing to another file) should work out-of-the-box as well, but if it doesn't, maybe dereferencing your document before passing it to openapi-zod-client could help
- You can check an example input (the petstore example when you open/reset editor.swagger.io) and output
- there's also an example of a programmatic usage
- or you can check the tests in the src folder which are mostly just inline snapshots of the outputs
`yaml`
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
"200":
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
tags:
- pets
responses:
"201":
description: Null response
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
responses:
"200":
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
items:
$ref: "#/components/schemas/Pet"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
output:
`ts
import { makeApi, Zodios } from "@zodios/core";
import { z } from "zod";
const Pet = z.object({ id: z.number().int(), name: z.string(), tag: z.string().optional() });
const Pets = z.array(Pet);
const Error = z.object({ code: z.number().int(), message: z.string() });
export const schemas = {
Pet,
Pets,
Error,
};
const endpoints = makeApi([
{
method: "get",
path: "/pets",
requestFormat: "json",
parameters: [
{
name: "limit",
type: "Query",
schema: z.number().int().optional(),
},
],
response: z.array(Pet),
},
{
method: "post",
path: "/pets",
requestFormat: "json",
response: z.void(),
},
{
method: "get",
path: "/pets/:petId",
requestFormat: "json",
parameters: [
{
name: "petId",
type: "Path",
schema: z.string(),
},
],
response: Pet,
},
]);
export const api = new Zodios(endpoints);
export function createApiClient(baseUrl: string) {
return new Zodios(baseUrl, endpoints);
}
`
- handle OA prefixItems -> output z.tuple
- rm unused (=never referenced) variables from output
NOT tested/expected to work with OpenAPI before v3, please migrate your specs to v3+ if you want to use this
- pnpm i && pnpm gen
if you fix an edge case please make a dedicated minimal reproduction test in the tests` folder so that it doesn't break in future versions