Documentation in FastAPI

FastAPI will automatically document your endpoints by using the OpenAPI standard and Swagger User Interface. In this post, we look at what that means and how to access your auto-generated documentation.

The OpenAPI Specification

FastAPI is built around the OpenAPI Specification, a widely used industry standard for describing RESTful APIs. The specification allows developers and non-developers to explore and understand the capabilities of a RESTful API without needing access to its source code, product documentation, or any other technical guidance.

The OpenAPI definition for an API product exists as a standard JSON or YAML document that describes information about the API, its version number, external servers, and endpoints. The paths also list HTTP methods to be performed on the APIs resources along with their responses.

Below is an example of a simple OpenAPI specification, written in YAML.

openapi: 3.0.0
info:
  version: 1.0.0
  title: Ice Cream Inventory API
  description: A sample API to illustrate OpenAPI concepts
paths:
  /get-all-items/:
	get:
	  description: Returns an inventory of ice cream
	  responses:
		'200':
		  description: Successful response

FastAPI comes equipped with the ability to configure OpenAPI conditionally, extend the OpenAPI schema, or use OpenAPI to document an external API callback. These are all more advanced features than what we’ll be covering in this series on FastAPI.

However, just be aware that the OpenAPI standard is how FastAPI is generating its documentation.

Swagger UI

Swagger UI is a tool used by developers and non-developers to interact with an API through a web browser. It can work with any API that conforms to the OpenAPI Specification, such as FastAPI.

Swagger UI reads the OpenAPI document that FastAPI produces from your endpoints. It then generates a list those endpoints, their HTTP methods and parameters, and the operations available to be performed on them. It also lets you test the endpoints within the Swagger user interface.

Every FastAPI app has a Swagger UI page generated from the API’s endpoints. The default page for FastAPI’s Swagger documentation is /docs/.

Below is an example of what Swagger UI looks like.

Available routes are color-coded by their request type. Opening the dropdown elements allows you to explore what parameters are allowed and what the possible response codes will be. Swagger UI also lets you test the routes by passing in data and executing the requests.

Swagger Alternatives

Swagger UI is not the only way to test your FastAPI app. A few alternatives are listed below that can replace Swagger UI completely, or they can be used in tandem.

Curl is a command-line tool used to manually interact with and test APIs. Curl is able to send different HTTP request methods to post, put, create, and delete data. It’s a more advanced tool than what beginners need when they’re just starting out. A book titled Everything curl is freely available for those wishing to learn more. The tool comes pre-installed on macOS and Windows. Run the CLI command below to see if curl is already installed on your system.

curl --version

ReDoc is a second tool that FastAPI uses to generate API documentation. It’s automatically created at the /redoc/ path in your application. If you have a FastAPI app running, navigate to http://127.0.0.1:8000/redoc to view ReDoc.

PostMan is a desktop app and a software-as-a-service tool that’s used for building and testing APIs. It helps simplify the API testing process by making it more accessible and automated.

One additional API tool to consider is Insomnia. Like the previously mentioned software, Insomnia lets you quickly and easily send REST, SOAP, GraphQL, and GRPC requests directly within the app. It also uses Swagger UI, can automate tests, and build pipelines with Git providers.

Summary

In this post we introduced the OpenAPI specification and Swagger UI to learn how FastAPI generates documentation. We also introduced alternatives to Swagger UI for building and testing APIs.

In the next post we look at how FastAPI handles HTTP Exceptions.