Integrate FastAPI with Speakeasy

Add a List of Servers to Your FastAPI App

This may seem obvious, but while first working with FastAPI in development, the generated docs, development server, and API operations all work out of the box without the need to manually specify your server address.

However, when generating SDKs, Speakeasy requires your OpenAPI spec to list servers.

If you start testing out Speakeasy in development for SDK generation, make sure to add a list of servers to your FastAPI app, starting with your local development server.

In our app/main.py, we added our local server as shown.

This leads to the following generated output in openapi.yaml.

Which, after Speakeasy generates the SDK, leads to the following abbreviated code in sdk/src/sdk/sdkconfiguration.py.

You'll find calls to SDKConfiguration.get_server_details() when the SDK builds API URLs.

Add a Title, Summary, Description, and Version to Your FastAPI App

In our app/main.py, if we have the following.

FastAPI generates the following yaml in our openapi.yaml file.

Which adds helpful text to the generated SDK documentation, including comments in the SDK code. For example, in sdk/src/sdk/sdk.py.

Speakeasy adds the version to the SDKConfiguration in sdk/src/sdk/sdkconfiguration.py.

Eventually, when your users call your API using the generated SDK, this version makes its way into the headers passed with requests. For example, in sdk/src/sdk/burger.py, we see that headers['user-agent'] includes a reference to SDKConfiguration.openapi_doc_version.

This way, your server logs will include the FastAPI App version along with other helpful details about the SDK.

Route-Level Customizations: Enhancing SDK Usability

With the basics out of the way, let's look at a few more substantial recommendations.

Add Typed Additional Responses to FastAPI Routes

When developers use your generated SDK, they may wish to see what all the possible responses for an API call could be.

With FastAPI, you can add additional responses to each route by specifying a response type.

In our app/main.py, we added this abbreviated code.

FastAPI adds a schema for our specific error message to openapi.yaml.

Speakeasy then generates documentation for this error in sdk/docs/models/errors/responsemessage.md and adds a data class in sdk/src/sdk/models/errors/responsemessage.py, so that the SDK returns typed errors when, for example, users try to request a burger that does not exist.

Group FastAPI Operations With OpenAPI Tags and Tag Metadata

As your API develops and grows bigger, you're likely to split your API into separate files. FastAPI provides conveniences (opens in a new tab) to help reduce boilerplate and repetition when splitting an API into multiple modules.

While this separation may reduce cognitive overhead while you're working in particular sections of the API code, it doesn't mean similar groups are automatically created in your documentation and SDK code.

We recommend you add tags to all operations in FastAPI, whether you're building a big application or only have a handful of operations so that operations can be grouped by tag in generated SDK code and documentation.

Add Tags to Operations

The most straightforward way to add tags is to edit each operation and add a list of tags. This example highlights the tags list.

Add Metadata to Tags

You can add metadata to your tags to further improve the developer experience of your SDK.

FastAPI accepts a parameter called openapi_tags, which we can use to add metadata, such as a description and a list of external documentation links.

Here's how to add metadata to tags.

How Tags Are Added to the OpenAPI Spec and SDK Code

When we add metadata to tags, FastAPI adds a top-level tags section to our OpenAPI spec.

Each tagged path in our OpenAPI spec also gets a list of tags.

Speakeasy then splits SDK files into separate modules and adds helpful links in docstrings and generated documentation. For example, in sdk/src/sdk/burger.py.

Customize the OpenAPI operationId Generated by FastAPI

When FastAPI outputs an OpenAPI spec, it generates a unique OpenAPI operationId for each path. By default, this unique ID is generated by the FastAPI generate_unique_id function.

For our operation that returns a burger by burger_id, this unique ID would be read_burger_burger__burger_id__get. This makes its way into SDK code, leading to class names such as ReadBurgerBurgerBurgerIDGetRequest or function names like read_burger_burger_burger_id_get.

Here's a usage example after generating an SDK without customizing the operationId.

To improve usability, we have three methods of customizing these generated strings.

Option 1: Change Method Names in Speakeasy with x-speakeasy-name-override

Firstly, we can add the top-level x-speakeasy-name-override extension to our OpenAPI spec, allowing Speakeasy to override these generated names when it generates SDK code.

To add this extension, follow the Speakeasy guide on changing method names.

Option 2: Customize the FastAPI generate_unique_id_function Function

The preferred alternative, though, is to use a custom function when you generate unique IDs for paths.

The example below is an illustrative function that doesn't generate guaranteed-unique IDs and doesn't handle method names without an underscore. However, it demonstrates how you can add a function that generates IDs based on an operation's method name.

Using our custom function above, our read_burger operation gets a much friendlier operation ID: readBurger. And our usage example becomes much easier to read.

Option 3: Add an Operation ID per Operation

With FastAPI, you can specify the operationId per operation. For our example, we'll add a new parameter called operation_id to the operation decorator.

Add Retries to Your SDK With x-speakeasy-retries

Speakeasy can generate SDKs that follow custom rules for retrying failed requests. For instance, if your server failed to return a response within a specified time, you may want your users to retry their request without clobbering your server.

To add retries to SDKs generated by Speakeasy, add 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 to each operation.

Adding Global Retries

To add global retries, we need to customize the schema generated by the FastAPI get_openapi function.

Keep in mind you'll need to add this customization after declaring your operation routes.

This change adds the following top-level section to openapi.yaml.

Adding Retries Per Request

To add x-speakeasy-retries to a single operation, update the operation and add the openapi_extra parameter as follows.

Add Webhooks for Real-Time Notifications

Starting with OpenAPI version 3.1.0, it is possible to specify webhooks for your application in OpenAPI. Speakeasy generates request and response objects for webhooks as part of SDK generation, which provides a consistent interface to your users.

Here's how to add a webhook to FastAPI:

FastAPI generates the following top-level webhooks section in openapi.yaml.

In turn, Speakeasy generates a model and corresponding documentation for WebhookOrderStatusChangedResponse.