Deploying docs from FastAPI

FastAPI is a Python framework that allows you to create APIs, and automatically generates their documentation, based on the OpenAPI specification.

This guide walks you through how to deploy API documents generated by FastAPI, and how to enrich and filter those to improve the reader experience.

Deploying docs from your local machine #

The following assumes your local machine is configured with Python and FastAPI, and that your main file is named main.py.

Create and name your first API documentation. Then, retrieve the name and token of this documentation from the CI deployment settings page.
Install the Bump.sh CLI with npm as below, or use alternative options, with
```
  npm install -g bump-cli
```
Launch your local server with
```
  uvicorn main:app --reload
```
Note: You might need, depending on how you usually run your Python commands, to prepend them with python3 -m.

Deploy your doc to Bump.sh with

  bump deploy http://127.0.0.1:8000/openapi.json \
 --doc my-documentation-name \
 --token my-documentation-token

That’s it! Enjoy the comfort of Bump.sh to browse through your API doc, and customize it to your needs.

Enriching documents #

By default, FastAPI generates what can be considered a plain technical description of your API. Although it is robust and complete, it’s not enough for people discovering your API without any upfront knowledge about it, access to the code, or ability to test it extensively. Such documents require contextual information, and any appropriate adjustements.

FastAPI lets you extend documents, using Python.

You can also accomplish this using OpenAPI’s Overlay specification, which can be convenient in all use cases where you do not want to change your Python code base (e.g. when involving Technical Writers or Product Managers in writing docs).

The Bump.sh CLI supports Overlays. Technically, the bump overlay command will output a modified version of the [DEFINITION_FILE] (an OpenAPI or AsyncAPI document) by applying the operations described in the [OVERLAY_FILE] Overlay file to the original API document.

Create your Overlay document (see example use cases in Augmenting Generated OpenAPI Documents with Filters & Overlays), and name it overlays.json (YAML and JSON are both supported as inputs for the CLI).

Apply your Overlay document to the original API document

  bump overlay http://127.0.0.1:8000/openapi.json overlays.json > openapi.updated.json

Deploy the resulting file to Bump.sh

  bump deploy openapi.updated.json \
 --doc my-documentation-name \
 --token my-documentation-token

Note: The diff computation performed by Bump.sh to display the API changelog is done when the resulting file is deployed. If you need to compute the diff before applying Overlays (for instance when your Overlay document filters out some information), consider using the bump diff command and the GitHub Action.