How To Generate an OpenAPI Spec With Fastify
In this tutorial, we'll show you how to generate an OpenAPI specification using Fastify (opens in a new tab). We will also show how you can use Speakeasy to generate client SDKs for your API based on the specification.
Example code
If you want to follow along with the example code in this tutorial, you can clone the Speakeasy Fastify example repo (opens in a new tab).
Here's what we'll cover:
- How to add
@fastify/swagger
to a Fastify project. - Generate an OpenAPI specification using the Fastify CLI.
- Improve the generated OpenAPI specification for better downstream SDK generation.
- Use the Speakeasy CLI to generate a client SDK based on our generated OpenAPI specification.
- Use the Speakeasy OpenAPI extensions to improve generated SDKs.
- How to automate this process as part of a CI/CD pipeline.
Your Fastify project might not be as simple as our example app, but the steps below should translate well to any Fastify project. We'll also look at how to gradually add routes to OpenAPI so that you have the option to ship an SDK that improves API coverage over time.
The SDK Generation Pipeline
Fastify ships with the @fastify/swagger
(opens in a new tab) plugin, which provides convenient shortcuts for generating good OpenAPI specifications. We'll start this tutorial by registering @fastify/swagger
in a Fastify project to generate a spec.
The quality of your OpenAPI specification will ultimately determine the quality of generated 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 generate SDKs using Speakeasy.
Finally, we'll add this process to a CI/CD pipeline so that Speakeasy automatically generates fresh SDKs whenever your Fastify API changes in the future.
Requirements
This guide assumes that you have an existing Fastify app or you'll clone our example application, and that you have a basic familiarity with Fastify.
You'll need Node.js installed (opens in a new tab) (we used Node v20.5.1), and you'll need to install the Fastify CLI (opens in a new tab).
Once you have Node.js, you can install the Fastify CLI by running the following in the terminal:
npm install fastify-cli --global
Make sure fastify
is in your $PATH
:
fastify version
If you can't run fastify
using the steps above, you can use npx
to run fastify-cli
by replacing fastify
with fastify-cli
in our code samples.
For example:
# fastify versionnpx fastify-cli version
Install the Speakeasy CLI to generate the SDK once you have generated your OpenAPI spec.
How To Add "@fastify/swagger" to a Fastify Project
In your Fastify project folder, run the following in the terminal to install @fastify/swagger
:
npm install --save @fastify/swagger
To register @fastify/swagger
in our Fastify app, we added a new plugin. Here's the simplified plugin we added as plugins/openapi.js
:
Without any further configuration, you can generate an OpenAPI specification by running the Fastify CLI:
fastify generate-swagger app.js
This should print a basic OpenAPI spec in JSON format.
TIP
If you find YAML more readable than JSON, you can add --yaml=true
to your fastify
commands:
fastify generate-swagger --yaml=true app.js
The option to output YAML is brand new (opens in a new tab) and, while merged, hasn't made it to a release when we wrote this tutorial.
Supported OpenAPI Versions in Fastify and Speakeasy
Fastify can generate OpenAPI specifications in OpenAPI version 2.0 (opens in a new tab) (formerly known as Swagger) or OpenAPI version 3.0.3 (opens in a new tab).
Speakeasy supports OpenAPI 3.x.
We need to configure Fastify to ensure we output an OpenAPI spec that conforms to OpenAPI 3.0.3.
How To Generate a Specification in OpenAPI Version 3.0.3 Using Fastify
In Fastify, the version of the generated OpenAPI specification is determined by the Fastify options object. To use OpenAPI 3.0.3, the options object should contain an object with the key openapi
at its root.
Continuing our example above, we'll add an options object when we register @fastify/swagger
in plugins/openapi.js
:
To verify that we now have an OpenAPI 3.0.3 spec, run:
fastify generate-swagger app.js
The output should start with the following JSON:
{ "openapi": "3.0.3" //...}
How To Add OpenAPI "info" in Fastify
Without customization, @fastify/swagger
generates the following info
object for our API:
{ //... "info": { "version": "8.10.1", "title": "@fastify/swagger" }}
We can customize this object by updating our options object in plugins/openapi.js
:
Fastify copies this info
object verbatim, which results in the following info
object in our JSON:
{ "info": { "title": "Speakeasy Bar API", "description": "This is a sample API for Speakeasy Bar.", "termsOfService": "http://example.com/terms/", "contact": { "name": "Speakeasy Bar Support", "url": "http://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } //...}
Another common pattern we've seen, included here for completeness, is to reuse information from the project's package.json
when generating OpenAPI specs. This pattern takes DRY (opens in a new tab) quite literally, and someone editing the package might not realize the downstream consequences.
To pull information from package.json
in plugins/openapi.js
:
Update Fastify to Generate OpenAPI Component Schemas
Fastify handles validation and serialization for Fastify apps based on schemas defined as JSON Schema but does not enforce separating schemas into reusable components.
Let's start with a hypothetical example in a route definition, routes/drink/index.js
:
The example above would generate the following OpenAPI schema for this route:
{ "paths": { "/drink/{drinkId}/": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "drinkId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } } }}
Note how the response schema is presented inline. If we defined the schema for another route that returns a drink object similarly, our OpenAPI spec, resulting SDK, and documentation would not present a drink as a reusable component schema.
Fastify provides methods to add and reuse schemas in an application.
As a start, let's separate the response schema and use the Fastify addSchema
method:
We added a field called $id
to our drink schema, then called fastify.addSchema()
to add this shared schema to the Fastify app. To use this shared schema, we reference it using the JSON Schema $ref
keyword, referencing the shared schema $id
field.
This generates the following OpenAPI schema:
{ "components": { "schemas": { "def-0": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "title": "Drink" } } }, "paths": { "/drink/{drinkId}/": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "drinkId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } } } } } }}
Note how, instead of defining the response schema inline with the path schema, we now have a component schema def-0
, which our path's response schema references as #/components/schemas/def-0
.
This is already more useful. But if we were to generate an SDK or documentation based on this schema, the autogenerated name def-0
would lead to documentation and methods for a schema component named def-0
.
Our next task is to customize this name.
Creating Useful OpenAPI "$ref" references in Fastify
By default, Fastify keeps track of all schemas added with fastify.addSchema()
and numbers them. The default internal function that builds these references (opens in a new tab) looks like this:
This function makes it clear where the def-0
reference in our generated OpenAPI specification came from.
Fastify allows us to override the buildLocalReference
function as part of our OpenAPI options object in plugins/openapi.js
:
By overriding buildLocalReference
in the snippet above, we help Fastify to use the $id
field as the component schema's reference. If we were to regenerate the OpenAPI spec now, we would see that def-0
is replaced by Drink
.
Customizing OpenAPI "operationId" Using Fastify
Each path's operationId
field in the OpenAPI specification is used to generate method names and documentation in SDKs.
To add operationId
to a route, add the field to the route's schema. For example:
This would generate the following OpenAPI schema:
{ "/drink/{drinkId}/": { "get": { "operationId": "getDrink", "responses": { "200": { "description": "Default Response" } } } }}
Add OpenAPI Tags to Fastify Routes
At Speakeasy, whether you're building a big application or only have a handful of operations, we recommend adding tags to all your Fastify routes so you can group them by tag in generated SDK code and documentation.
Add OpenAPI Tags to Routes in Fastify
To add OpenAPI tags to a route in Fastify, add the tags
keyword with a list of tags to the route's schema. Here's a simplified example from routes/drink/index.js
:
Add Metadata to Tags
We can add a description and external documentation link to each tag by adding a list of tag objects to the Swagger options object in plugins/openapi.js
:
As with the other keys in the info
options, Fastify copies the list of tags to the generated OpenAPI spec verbatim.
Add a List of Servers to the Fastify OpenAPI Spec
When validating an OpenAPI spec, Speakeasy expects a list of servers at the root of the spec. We'll add this to our options object in plugins/openapi.js
:
Add Retries to Your SDK With "x-speakeasy-retries"
If you are using Speakeasy to generate your SDK, we can customize it to 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 SDKs generated by Speakeasy 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
Fastify respects OpenAPI extensions that start with x-
and copies these to the root of the generated OpenAPI specification.
Adding Retries per Method
If we want to add a unique retry strategy to a single route, we can add x-speakeasy-retries
to the route's schema:
Once again, when generating an OpenAPI spec, Fastify will copy route-specific OpenAPI extensions without any changes.
How To Generate an SDK Based on Your OpenAPI Spec
Before generating an SDK, we need to save the Fastify-generated OpenAPI spec to a file. We'll add the following script to our package.json
to generate openapi.json
in the root of our project:
Then we run the following in the terminal:
npm run openapi
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 generate 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.json
when prompted for the OpenAPI document location and select TypeScript when prompted for which language you would like to generate.
Add SDK Generation to Your GitHub Actions
The Speakeasy sdk-generation-action
(opens in a new tab) repository provides workflows that can integrate the Speakeasy CLI in your CI/CD pipeline, so your SDKs are regenerated 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 documentation about SDK Generation Action and Workflows (opens in a new tab).
Summary
In this tutorial, we've learned how to generate an OpenAPI specification for your Fastify API. We also learn how to integrate Fastify with Speakeasy to generate SDKs. The tutorial guides you through step-by-step instructions on how to do this, from adding @fastify/swagger
to a Fastify project and generating an OpenAPI specification to improving the generated OpenAPI specification for better SDK generation.
It also covers how to use the Speakeasy OpenAPI extensions to improve generated SDKs and how to automate SDK generation as part of a CI/CD pipeline.
Following these steps, you can successfully generate OpenAPI specifications for your Fastify app and improve your API operations.