How To Generate an OpenAPI Spec With tRPC
In this tutorial, we'll explore how to generate an OpenAPI document for our tRPC (opens in a new tab) API, and then we'll use this document to create an SDK using Speakeasy.
Here's what we'll cover:
- Adding
trpc-openapi
to a tRPC project. - Generating an OpenAPI specification using
trpc-openapi
. - Improving the generated OpenAPI specification for better downstream SDK generation.
- Using the Speakeasy CLI to create an SDK based on the generated OpenAPI specification.
- Using the Speakeasy OpenAPI extensions to improve created SDKs.
- Automating this process as part of a CI/CD pipeline.
TIP
If you want to follow along, you can use the tRPC Speakeasy Bar example repository (opens in a new tab).
The SDK Creation Pipeline
tRPC does not natively export OpenAPI documents, but the trpc-openapi
(opens in a new tab) package adds this functionality. We'll start this tutorial by adding trpc-openapi
to a project, and then we'll add a script to generate an OpenAPI schema and save it as a file.
The quality of your OpenAPI specification will ultimately determine the quality of created SDKs and documentation, so we'll dive into ways you can improve the generated specification.
With our new and improved OpenAPI specification in hand, we'll take a look at how to create SDKs using Speakeasy.
Finally, we'll add this process to a CI/CD pipeline so that Speakeasy automatically creates fresh SDKs whenever your tRPC API changes in the future.
Requirements
To follow along with this tutorial, you will need:
- An existing tRPC app, or you can clone our example application.
- Some familiarity with tRPC.
- Node.js (opens in a new tab) installed (we used Node v20.5.1).
- The Speakeasy CLI installed. You'll use the CLI to create the SDK once you have generated your OpenAPI spec.
Supported OpenAPI Versions
Speakeasy supports OpenAPI v3 and v3.1. As of October 2023, trpc-openapi
can generate schemas that adhere to the OpenAPI v3.0.3 specification (opens in a new tab).
This OpenAPI version is not a limitation, but it is important to keep the versions used in mind when debugging code generation. Refer to the OpenAPI Initiative for an overview of the differences between OpenAPI 3.0 and 3.1.0 (opens in a new tab).
How To Generate an OpenAPI Spec With tRPC
We'll use trpc-openapi
(opens in a new tab) to create REST endpoints for our tRPC procedures and then create the OpenAPI spec that describes these endpoints.
To generate an OpenAPI spec for tRPC, we'll use trpc-openapi (opens in a new tab) to create REST endpoints for our tRPC procedures, then create an OpenAPI document that describes these endpoints.
Add trpc-openapi to a Project
Install trpc-openapi
:
npm install trpc-openapi
Use initTRPC.meta<OpenApiMeta>()
to create a new tRPC instance with OpenAPI support:
Add OpenAPI meta to a procedure by passing an openapi
object to the meta
function. This object contains the HTTP method and path for the generated REST endpoint.
Add a new script to generate an OpenAPI document based on the tRPC router:
Add a script to save the generated OpenAPI document to a file:
Run the script to generate an OpenAPI document:
ts-node generateOpenApi.ts > openapi-spec.json
Add this document to the package.json
file as a script:
From now on, we can generate an OpenAPI document by running npm run generate-openapi
.
When we inspect the generated OpenAPI document, we can see that it contains a single endpoint for the findByProductCode
procedure, but it's missing a lot of information.
Let's see how we can improve this document.
How To Improve the OpenAPI Info Section
The OpenAPI info section contains information about the API, such as the title, description, and version. If you use Speakeasy later, it will use this information to create documentation and SDKs.
The GenerateOpenApiDocumentOptions
type from trpc-openapi
allows us to add this information to our OpenAPI document:
We can add this information to our generateOpenApiDocument
call:
Run npm run generate-openapi
and see how this information is added to the OpenAPI document:
Improving the OpenAPI Paths
We can improve our OpenAPI document by adding fields to the procedure's input and output schemas, and by adding examples, documentation, and metadata.
Expanding the Procedure’s Input and Output Schemas
Let's create a Drink
model and add a few field types to see how these are represented in the OpenAPI document.
Create a new file called models.ts
and specify a Drink
model using Zod:
Back in the router.ts
file, import these models and update the procedure's input and output schemas. In the example app, we also added a mock database.
If we regenerate the OpenAPI document, we can see that the Drink
model is now included in the document with all of its fields:
Speakeasy will use the descriptions in these fields to create documentation for the SDK.
OpenAPI Model Schemas in tRPC
At Speakeasy, we recommend using OpenAPI model schemas so that schemas are reusable across multiple procedures. This simplifies SDK code creation, makes it easier to maintain your OpenAPI document, and provides a better developer experience for your users.
At the time of writing, there is an open issue on the tRPC repository (opens in a new tab) to add support for OpenAPI model schemas. Until this is implemented, we'll need to be content with the duplication of schemas across procedures.
Under the hood, trpc-openapi
uses the Zod to Json Schema (opens in a new tab) package, which supports custom strategies for generating references to schemas, but this functionality is not yet exposed in trpc-openapi
.
Adding a Summary, Description, Examples, and Tags to a Procedure
We can enrich our OpenAPI document by adding a summary, description, examples, and tags to our procedure's metaobject.
The trpc-openapi
package uses these fields to generate the summary
, description
, example
, and tags
fields in the OpenAPI document.
The example
field is also used to add examples to the input schema.
If we regenerate the OpenAPI document now, we can see that the summary
, description
, and example
fields have been added to it.
Add Metadata to Tags
The trpc-openapi
package defines tags as a list of strings, but OpenAPI allows you to add metadata to tags. For example, you can add a description or a link to documentation to a tag.
Since trpc-openapi
uses the openapi-types
package (opens in a new tab) OpenAPIV3.Document
type, which allows tags defined as a list of strings or a list of objects, we can extend our document to include tag objects with metadata even though trpc-openapi
uses a list of strings.
Let's add a description to the drinks
tag:
Now we can see that the description
field has been added to the drinks
tag in the generated OpenAPI document:
Add Speakeasy Extensions to Methods
The OpenAPI vocabulary can sometimes be insufficient for your code creation needs. For these situations, Speakeasy provides a set of OpenAPI extensions. For example, you may want to give an SDK method a different name from the OperationId
. You can use the Speakeasy x-speakeasy-name-override
extension to do so.
This time, unfortunately, the openapi-types
package (opens in a new tab) OperationObject
type does not allow for custom extensions, so we need to add the extension to the generated OpenAPI document manually.
Ideally, we would create a new type that extends OpenAPIV3.Document
and adds the x-speakeasy-name-override
extension to the OperationObject
type, but for this tutorial, we'll keep it simple and add the extension by casting the path item to any
.
Let's add an x-speakeasy-name-override
extension to the findByProductCode
procedure.
First, we extend the OpenAPIV3.OperationObject
and OpenAPIV3.Document
types to add the x-speakeasy-name-override
and other extensions:
Then we import our extended operation type and add the x-speakeasy-name-override
extension to the findByProductCode
procedure:
Add Retries to an SDK With x-speakeasy-retries
Speakeasy can create SDKs that follow custom rules for retrying failed requests. For instance, if your server fails to return a response within a specified time, you may want your users to retry their request without clobbering your server.
Add retries to Speakeasy-created SDKs by adding a top-level x-speakeasy-retries
schema to your OpenAPI spec. You can also override the retry strategy per operation by adding x-speakeasy-retries
.
Adding Global Retries and Retries per Endpoint
Let's add a global retry strategy to our OpenAPI document and override it for our findByProductCode
procedure.
Regenerate the OpenAPI document and you can see that the x-speakeasy-retries
field has been added to the document.
Why Speakeasy and tRPC?
tRPC's focus on type safety and developer experience sets it apart from other TypeScript API frameworks. By using TypeScript's type system along with a schema library like Zod, tRPC allows your server and client code to share types.
One of tRPC's stated goals is to cut down on the need for codegen, but we believe there is still a place for code generation in the tRPC ecosystem. While tRPC's default client (opens in a new tab) is useful for writing internal clients in a monorepo where a client can import the server's AppRouter
, it does not make it easy to publish production-ready SDKs for use by internal and external developers. Nor does tRPC's type-safety extend to SDKs in languages other than TypeScript.
Speakeasy can help you create type-safe, production-ready SDKs for your tRPC API in various languages so that you can focus on building your API, confident that your users will have a great developer experience.
How To Create an SDK Based on the OpenAPI Spec
After following the steps above, we have an OpenAPI spec that is ready to use as the basis for a new SDK. Now we'll use Speakeasy to create an SDK.
In the root directory of your project, run the following:
speakeasy quickstart
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-spec.json
when prompted for the OpenAPI document location and select TypeScript when prompted for which language you would like to generate.
Add SDK Creation to GitHub Actions
The Speakeasy sdk-generation-action
(opens in a new tab) repository provides workflows to integrate the Speakeasy CLI in your CI/CD pipeline so that your client SDKs are recreated when your OpenAPI spec changes.
You can set up Speakeasy to automatically push a new branch to your SDK repositories so that your engineers can review and merge the SDK changes.
For an overview of how to set up automation for your SDKs, see the Speakeasy SDK Generation Action and Workflows documentation.