Embedding a Redoc subsite for OpenAPI (HTTP API) documentation

FastAPI, the Python framework for building web applications, automatically generates OpenAPI specifications. Documenteer provides built-in support for embedding a Redoc subsite for this OpenAPI documentation in a Rubin user guide. This solution combines the Documenteer Sphinx extension documenteer.ext.openapi to install the OpenAPI specification into the docs from your FastAPI application and the third-party extension sphinxcontrib-redoc to embed the Redoc subsite into your Sphinx documentation site.

1. Create a function to generate the OpenAPI docs

The first step is to create or identify a function that generates an OpenAPI specification for your application as a JSON-serialized string. This function must be importable from the Sphinx build process. For SQuaRE/Safir-standardized FastAPI applications, it may make sense to add this function to the main.py module where the FastAPI application is defined:

src/main.py
import json

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi


app = FastAPI()


def create_openapi() -> str:
    """Create the OpenAPI spec for static documentation."""
    spec = get_openapi(
        title=app.title,
        version=app.version,
        description=app.description,
        routes=app.routes,
    )
    return json.dumps(spec)

Note

This step is not necessary if the OpenAPI specification is already available in the source repository or is generated by a separate build process. See the note in step 3 on configuring an existing OpenAPI specification.

2. Add a stub page for the Redoc subsite

In your Sphinx documentation project, add a stub page for the Redoc subsite. This step adds the Redoc page to the Sphinx toctree and therefore to the Sphinx site navigation.

First, create the stub file:

docs/api.rst
########
REST API
########

This is a stub page for the API.

Then add this page to the site’s toctree:

docs/index.rst
.. toctree::

   api

3. Configuration in documenteer.toml

In the Sphinx project’s documenteer.toml configuration file, add a [project.openapi] table:

docs/documenteer.toml
[project.openapi]
openapi_path = "_static/openapi.json"
doc_path = "api"

[project.openapi.generator]
function = "example.main:create_openapi"

The openapi_path key specifies the path to the OpenAPI specification file, relative to the Sphinx project root. The doc_path key specifies the path to the Redoc subsite, relative to the Sphinx project root, and should match the path of the stub page created in step 2.

The function key specifies the import path to the function in your app that generates the OpenAPI specification. This field is formatted as <module>:<function>. For example, if the function called create_openapi is in the main.py module of the example package, the value would be "example.main:create_openapi".

If the function takes positional or keyword arguments, you can specify them in the positional_args and keyword_args keys, respectively.

docs/documenteer.toml
[project.openapi.generator]
function = "example.main:create_openapi"
positional_args = ["arg1", "arg2"]
keyword_args = {kwarg1 = "value1", kwarg2 = "value2"}

Note

If the OpenAPI specification is already available, you don’t need to specify the [project.openapi.generator] table. Ensure that the openapi_path key is set to the OpenAPI specification file’s path, relative to the Sphinx project root. If necessary, you can create a symlink to ensure the OpenAPI specification is available within the documentation source directory.

Additional resources