How to generate an OpenAPI document with FastAPI

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, your OpenAPI document needs to list servers.

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

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

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

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

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

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.

As your API develops and grows bigger, you’re likely to split it 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.

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

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

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.

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

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

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

This can often lead to cumbersome and unintuitive names. To improve usability, we have two methods of customizing these generated strings.

The preferred method 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.

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.

Starting with OpenAPI version 3.1.0, it is possible to specify webhooks for your application in OpenAPI.

Here’s how to add a webhook to FastAPI:

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

Now that we have a customized OpenAPI document, we can use Speakeasy to generate SDKs based on it. Let’s take a look at how the information we detailed in the OpenAPI document affects how Speakeasy generates SDKs.

After we added our local server information, this is how it generates in the openapi.yaml file.

After Speakeasy generates the SDK, this leads to the following abbreviated code in sdk/src/openapi/sdkconfiguration.py.

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

Speakeasy uses the title, summary, and descriptions we provided earlier to add 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/openapi/sdkconfiguration.py. It also uses this version to construct the user agent (user_agent), which contains the version of the SDK, the version of the Speakeasy generator build, and the version of the OpenAPI documentation.

When users call your API using the generated SDK, the user_agent from SDKConfiguration is automatically added to the user-agent header. The _build_request_with_client method in BaseSDK constructs the HTTP request and sets the header using headers[user_agent_header] = self.sdk_configuration.user_agent.

The unique operation_id generated by FastAPI does not translate well into an SDK. We need to customize the unique operation_id that FastAPI generates for better readability.

For instance, in the operation that returns a burger by burger_id, the default 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.

However, after using the custom function generate_unique_id we defined previously, the read_burger operation gets a much friendlier operation ID: readBurger. And the usage example becomes much easier to read.

In addition to the two methods described earlier for customizing the operation_id, there is a third way. We can add the top-level x-speakeasy-name-override extension to our OpenAPI document, allowing Speakeasy to override these generated names when it generates SDK code.

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

Speakeasy can generate 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.

To add retries to SDKs generated by Speakeasy, add a top-level x-speakeasy-retries schema to your OpenAPI document. You can also override the retry strategy per operation by adding x-speakeasy-retries to each operation.

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.

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

FastAPI supports several authentication mechanisms that can be easily integrated into your API.

The example below demonstrates adding an API key authentication scheme to the /burger/ endpoint of our API. We use the APIKeyHeader dependency to validate the API key passed in the Authorization header.

We can pass a key parameter to the list_burgers function, retrieve the API key from the header, and perform validation.

Now when generating the OpenAPI document, the API key authentication scheme will be included and only required for the listing on the /burger/ endpoint.