How To Generate an OpenAPI Spec With Zod
Zod is a powerful and flexible schema validation library for TypeScript. Many users define their TypeScript data parsing schemes using it.
In this tutorial, we'll take a detailed look at how to set up Zod OpenAPI to generate an OpenAPI schema based on Zod schemas. Then we'll use Speakeasy to read our generated OpenAPI schema and generate a production-ready client SDK.
An Example Schema: Burgers and Orders
We'll start with a tiny example schema describing two main types: Burgers and Orders. A burger is a menu item with an ID, name, and description. An order has an ID, a non-empty list of burger IDs, the time the order was placed, a table number, a status, and an optional note for the kitchen.
Anticipating our CRUD app, we'll also add additional schemas describing fields for creating new objects without IDs or updating existing objects where all fields are optional.
An Overview of Zod OpenAPI
Zod OpenAPI (opens in a new tab) is a TypeScript library that helps developers define OpenAPI schemas as Zod schemas. The stated goal of the project is to cut down on code duplication, and it does a wonderful job of this.
Zod schemas map to OpenAPI schemas well, and the changes required to extract OpenAPI documents from a schema defined in Zod are often small.
Zod OpenAPI is maintained by one of the contributors to an earlier library called Zod to OpenAPI (opens in a new tab). If you already use Zod to OpenAPI, the syntax will be familiar and you should be able to use either library. If you'd like to convert your Zod to OpenAPI code to Zod OpenAPI code, the Zod OpenAPI library provides helpful documentation for migrating code (opens in a new tab).
Step-by-Step Tutorial: From Zod to OpenAPI to an SDK
Now let's walk through the process of generating an OpenAPI schema and SDK for our Burgers and Orders API.
1. Create Your Zod Project
If you would like to follow along, start by creating a new directory for your project. We'll call ours zod-burgers
.
Then, initialize a new npm project and install Zod:
2. Install the Zod OpenAPI Library
Use npm to install zod-openapi
:
3. Create Your App's First Zod Schema
Save this TypeScript code in a new file called index.ts
.
4. Extend Zod With OpenAPI
We'll add the openapi
method to Zod by calling extendZodWithOpenApi
once. Update index.ts
to import extendZodWithOpenApi
from zod-openapi
, then call extendZodWithOpenApi
.
5. Register and Generate a Component Schema
Next, we'll use the new openapi
method provided by extendZodWithOpenApi
to register an OpenAPI schema for the burgerSchema
. Edit index.ts
and add .openapi({ref: "Burger"}
to the burgerSchema
schema object.
We'll also add an OpenAPI generator, OpenApiGeneratorV31
, and log the generated component to the console as YAML.
6. Add Metadata to Components
To generate an SDK that offers great developer experience, we recommend adding descriptions and examples to all fields in OpenAPI components.
With Zod OpenAPI, we'll call the .openapi
method on each field, and add an example and description to each field.
We'll also add a description to the Burger
component itself.
Edit index.ts
and edit burgerSchema
to add OpenAPI metadata.
7. Prepare to Generate an OpenAPI Document
Now that we know how to register components with metadata for our OpenAPI schema, let's generate a complete schema document.
Import yaml
and createDocument
.
8. Generate an OpenAPI Document
We'll use the createDocument
method to generate an OpenAPI document. We'll pass in the burgerSchema
and a title for the document.
9. Run the Code
Run the code in the terminal:
10. Add a Burger ID Schema
To make the burger ID available to other schemas, we'll define a burger ID schema. We'll also use this schema to define a path parameter for the burger ID later on.
Let's create the burger ID schema now.
11. Replace the Burger ID Field With a Reference
We'll replace the burger ID field with a reference to the burger ID schema.
12. Add a Schema for Creating Burgers
We'll add a schema for creating burgers that doesn't include an ID. We'll use this schema to define the request body for the create burger path.
13. Add Paths
Paths define the endpoints of your API. For our burger restaurant, we might define endpoints for creating, reading, updating, and deleting burgers and orders.
To register paths and webhooks, we'll define paths as objects of type ZodOpenApiOperationObject
, then add our paths and webhooks to the document definition.
Start by importing ZodOpenApiOperationObject
from zod-openapi
.
14. Add a Create Burger Path
We'll add a path for creating a new burger. We'll use the ZodOpenApiOperationObject
type to define the path.
15. Add a Read Burger Path
We'll add a path for fetching a burger by ID. We'll use the ZodOpenApiOperationObject
type to define the path.
16. Add a Webhook That Runs When a Burger Is Created
We'll add a webhook that runs when a burger is created. We'll use the ZodOpenApiOperationObject
type to define the webhook.
17. Register Paths and Webhooks
We'll register our paths and webhooks by adding them to the document definition.
18. Run the Code
Run the code in the terminal:
4. Extend Zod With OpenAPI
We'll add the openapi
method to Zod by calling extendZodWithOpenApi
once. Update index.ts
to import extendZodWithOpenApi
from zod-openapi
, then call extendZodWithOpenApi
.
5. Register and Generate a Component Schema
Next, we'll use the new openapi
method provided by extendZodWithOpenApi
to register an OpenAPI schema for the burgerSchema
. Edit index.ts
and add .openapi({ref: "Burger"}
to the burgerSchema
schema object.
We'll also add an OpenAPI generator, OpenApiGeneratorV31
, and log the generated component to the console as YAML.
6. Add Metadata to Components
To generate an SDK that offers great developer experience, we recommend adding descriptions and examples to all fields in OpenAPI components.
With Zod OpenAPI, we'll call the .openapi
method on each field, and add an example and description to each field.
We'll also add a description to the Burger
component itself.
Edit index.ts
and edit burgerSchema
to add OpenAPI metadata.
7. Prepare to Generate an OpenAPI Document
Now that we know how to register components with metadata for our OpenAPI schema, let's generate a complete schema document.
Import yaml
and createDocument
.
8. Generate an OpenAPI Document
We'll use the createDocument
method to generate an OpenAPI document. We'll pass in the burgerSchema
and a title for the document.
10. Add a Burger ID Schema
To make the burger ID available to other schemas, we'll define a burger ID schema. We'll also use this schema to define a path parameter for the burger ID later on.
Let's create the burger ID schema now.
11. Replace the Burger ID Field With a Reference
We'll replace the burger ID field with a reference to the burger ID schema.
12. Add a Schema for Creating Burgers
We'll add a schema for creating burgers that doesn't include an ID. We'll use this schema to define the request body for the create burger path.
13. Add Paths
Paths define the endpoints of your API. For our burger restaurant, we might define endpoints for creating, reading, updating, and deleting burgers and orders.
To register paths and webhooks, we'll define paths as objects of type ZodOpenApiOperationObject
, then add our paths and webhooks to the document definition.
Start by importing ZodOpenApiOperationObject
from zod-openapi
.
14. Add a Create Burger Path
We'll add a path for creating a new burger. We'll use the ZodOpenApiOperationObject
type to define the path.
15. Add a Read Burger Path
We'll add a path for fetching a burger by ID. We'll use the ZodOpenApiOperationObject
type to define the path.
16. Add a Webhook That Runs When a Burger Is Created
We'll add a webhook that runs when a burger is created. We'll use the ZodOpenApiOperationObject
type to define the webhook.
19. Generate an SDK
With our OpenAPI schema complete, we can now generate an SDK using the Speakeasy SDK generator. We'll follow the instructions in the Speakeasy documentation to generate SDKs for various platforms.
First, write your YAML schema to a new file called openapi.yaml
. Run the following in the terminal:
Then, log in to your Speakeasy account or use the Speakeasy CLI to generate a new SDK.
Here's how to use the CLI. In the terminal, run:
Follow the onscreen prompts to provide the necessary configuration details for your new SDK such as the name, schema location and output path. Enter openapi.yaml
when prompted for the OpenAPI document location and select Python when prompted for which language you would like to generate.
Example Zod Schema and SDK Generator
The source code for our complete example is available in the zod-burgers
(opens in a new tab) repository.
The repository contains a pre-generated Python SDK with instructions on how to generate more SDKs.
You can clone this repository to test how changes to the Zod schema definition result in changes to the generated SDK.
Summary
In this tutorial, we learned how to generate OpenAPI schemas from Zod and create client SDKs with Speakeasy.
By following these steps, you can ensure that your API is well-documented, easy to use, and offers a great developer experience.