Open API Pages

Totally Pythonic, OpenAPI Based customizable documentation pages for SwaggerUI, ReDoc, RapiDoc, Elements, Scalar.

Keep in mind, that this package doesn't generate OpenAPI Spec, it just renders the pages with the given configuration.

Table of Contents

• Open API Pages
  • Table of Contents
  • Features
    • Progress
  • Installation
  • Usage
    • FastAPI
    • Litestar
  • Motivation
    • Developer Experience
    • Configuration
    • Alternatives
    • Standardisation
  • See Also
    • Projects
    • Issues, PRs, and Discussions
  • Tasks
    • Testing
    • CI/CD Pipeline
    • Coverage Configuration
    • Development Tasks
  • Author
  • Disclaimer
  • License

Features

Gimme an OpenAPI Spec, leave the rest to me...

• Framework agnostic.
• Only one runtime dependency: typing-extensions.
• Fully typed.
• Highly extensible.

Progress

Emoji Key:

Installation

# Using uv (recommended)
uv add openapipages

# Using pip
pip install openapipages

Usage

I know it looks a bit boilerplate but it's all straight-forward. The .render() method returns the HTML as a string. Thanks to this design, you can extend and configure the pages as you wish (e.g. add extra logic to restrict access to the page).

FastAPI

The include_in_schema parameter is set to False in each endpoint to avoid including these endpoints in the OpenAPI Spec.

from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from openapipages import Elements, RapiDoc, ReDoc, Scalar, SwaggerUI

# Disable the built-in /redoc page so we can make a custom one.
app = FastAPI(redoc_url=None)


@app.get("/")
def root() -> dict[str, str]:
    return {"Hello": "World"}


@app.get("/swaggerui", response_class=HTMLResponse, include_in_schema=False)
def get_swaggerui() -> str:
    return SwaggerUI(title="Swagger UI").render()


@app.get("/redoc", response_class=HTMLResponse, include_in_schema=False)
def get_redoc() -> str:
    return ReDoc(title="ReDoc").render()


@app.get("/scalar", response_class=HTMLResponse, include_in_schema=False)
def get_scalar() -> str:
    return Scalar(title="Scalar").render()


@app.get("/elements", response_class=HTMLResponse, include_in_schema=False)
def get_elements() -> str:
    return Elements(title="Elements").render()


@app.get("/rapidoc", response_class=HTMLResponse, include_in_schema=False)
def get_rapidoc() -> str:
    return RapiDoc(title="RapiDoc").render()

Litestar

See the Litestar Example for more details.

Motivation

TL;DR - I don't want to copy and paste it again...

Developer Experience

Several API Documentation tools are ready to use at your fingertips with a standard interface.

No more copying and pasting the same thing from one project to another. Import the package and use it!

Configuration

Here is a pull request made to the FastAPI repo. This was the point I understood the configuration was limited and it wouldn't change...

• Allow passing ui parameters to redoc html by adriantre · Pull Request #10437 · tangelo/fastapi

Also, the author's answer to this PR shows that we won't be seeing more alternative documentation tools in the future.

Alternatives

Here is another pull request made to the FastAPI repo. It brings Scalar support, but it's not approved/merged yet and I think it will stay that way thanks to the previous PR.

• feat: add scalar integration (additional alternative to Swagger UI/Redoc) by marclave · Pull Request #10674 · tiangolo/fastapi

Standardisation

A standard interface for many API Documentation Interfaces with configuration features.

Lately, OpenAPI Spec-based Documentation tools have become popular in the Python community. We see a lot of projects (FastAPI, Litestar, APISpec, flasgger, SpecTree, Connexion, etc) offering support for OpenAPI Specification out of the box.

Litestar has support for SwaggerUI, ReDoc, RapiDoc, and Elements and FastAPI has support for SwaggerUI, and ReDoc but what is next? Will the next one be enough?

They all have one thing in common, some HTML (as Python string or a file) templated with the given configuration.

Do you see where I am going?

I want openapipages to be SQLAlchemy of OpenAPI Spec-based Documentation tools.

One interface for many! And of course Framework agnostic... So you can use it in your FastAPI, Litestar projects, or any other project that generates OpenAPI specifications.

See Also

Projects

• kemingy/defspec: Create the OpenAPI spec and document from dataclass, attrs, etc.
• spec-first/swagger_ui_bundle: bundled swagger-ui pip package
• spec-first/connexion: Connexion is a modern Python web framework that makes spec-first and api-first development easy.
• sveint/flask-swagger-ui: Swagger UI blueprint for flask
• flasgger/flasgger: Easy OpenAPI specs and Swagger UI for your Flask API
• marshmallow-code/apispec: A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..
• jmcarp/flask-apispec

Issues, PRs, and Discussions

• [Question] Is it possible to load the Swagger UI offline? · Issue #261 · 0b01001001/spectree
• Swagger with hosted files does not work after upgrade · tiangolo/fastapi · Discussion #10426
• ♻️ Generate cleaner Swagger HTML by s-rigaud · Pull Request #11072 · tiangolo/fastapi

Author

• Hasan Sezer Tasan, It's me 👋

Disclaimer

FastAPI and Litestar projects and the two pull requests mentioned above inspired me to create this package.

Tasks

Testing

The suite is organised in layers under tests/:

• tests/unit/ — renderer/Base logic tested directly (no HTTP).
• tests/integration/ — each renderer rendered through a FastAPI app over an in-process ASGI client.
• tests/e2e/ — real-browser (Playwright/Chromium) tests that boot each UI, load its JS from the CDN, and verify the spec renders.

Run the cross-version unit and integration suites with tox:

uv sync                         # install development dependencies
uv run --locked tox run         # style checks and the supported Python matrix
uv run --locked tox run -e 3.14 # run the suite on one Python version
uv run --locked tox run -e style,sast

The end-to-end tests run separately from the cross-platform matrix. They load each UI's JavaScript from its real CDN, so they need network access and run Chromium only:

uv run --locked tox run -e e2e      # installs Chromium, then runs tests/e2e
uv run --locked tox run -e coverage # combine and report the matrix's coverage

CI runs these tests in a dedicated E2E (Chromium) job after the cross-platform test matrix.

CI/CD Pipeline

The project uses GitHub Actions for continuous integration:

• Tests: Runs on multiple Python versions (3.10-3.14) and operating systems
• Coverage: Generates and uploads coverage reports to Codecov
• Static Analysis: Runs style checks and type checking
• Artifacts: Coverage files are uploaded as artifacts for debugging

Coverage Configuration

• Coverage is configured to target 99% minimum coverage
• Coverage collection includes openapipages and the unit and integration tests; the Codecov project status targets src
• Excluded files: __about__.py, end-to-end tests, and pragma-marked lines
• Parallel coverage collection enabled for CI

Development Tasks

This project includes comprehensive Visual Studio Code configurations for enhanced development experience:

Debugging Configurations (.vscode/launch.json)

• Python: Current File - Debug the currently open Python file
• Python: Tests - Run all tests with pytest under the debugger
• Python: Debug Test File - Debug the currently open test file with pytest
• Python: Run Tests with Coverage - Run tests under coverage run --module pytest (e2e excluded, as in CI); follow with coverage combine && coverage report
• Python: FastAPI Example Server - Debug examples/fastapi/main.py directly
• Python: Litestar Example Server - Debug examples/litestar/main.py directly
• Python: Debug with uvicorn (FastAPI) - Serve examples.fastapi.main:app on port 8000 under the debugger
• Python: Debug with uvicorn (Litestar) - Serve examples.litestar.main:app on port 8001 under the debugger
• Python: Debug with uvicorn (Test Server) - Serve tests.main:app on port 8002 under the debugger
• Python: Attach - Attach the debugger to a process listening on localhost:5678

Build Tasks (.vscode/tasks.json)

• Install Dependencies - Install project dependencies using uv
• Run Tests - Run tests with pytest
• Run Tests with Coverage - Run tests with coverage reporting
• Lint Code - Run ruff linter
• Format Code - Format code with ruff
• Type Check - Run mypy type checking
• Run All Checks - Run linting, type checking, and tests
• Start FastAPI Example Server - Start the FastAPI example server
• Start Litestar Example Server - Start the Litestar example server
• Start Test Server - Start the test server
• Build Package - Build the package using uv
• Clean Build Artifacts - Remove the build/ and dist/ directories

Workspace Settings (.vscode/settings.json)

• Configured Python interpreter path
• Enabled ruff for linting and formatting
• Configured pytest for testing
• Set up file exclusions for cache and build artifacts
• Enabled format on save and code actions
• Configured Python analysis settings

Usage

To use these configurations:

1. Open the project in Visual Studio Code
2. Press F5 or go to Run and Debug panel to access debugging configurations
3. Use Ctrl+Shift+P (or Cmd+Shift+P on macOS) and type "Tasks: Run Task" to access build tasks
4. The workspace settings will be automatically applied

License

openapipages is distributed under the terms of the MIT license.