FastAPI Offline Docs

Common errors

• Documentation UI (Swagger/Redoc) not loading or showing old content in browser.

  cause The `fastapi-offline` version is too old for the `fastapi` version, leading to incompatible bundled assets, or a custom `static_url` is misconfigured.
  fix Update `fastapi-offline` to the latest version (`pip install --upgrade fastapi-offline`). If you use a custom `static_url`, ensure it's correctly configured to point to the `fastapi-offline`'s served static files (default is `/static-offline-docs`).

• ModuleNotFoundError: No module named 'fastapi_offline'

  cause The `fastapi-offline` package is not installed in your current Python environment.
  fix Install the package using pip: `pip install fastapi-offline`.

• AttributeError: 'FastAPI' object has no attribute 'get_swagger_ui_html' (or similar internal doc-related FastAPI errors).

  cause This error often occurs when `fastapi-offline` is intended to manage the documentation routes, but internal FastAPI functions are being called directly or implicitly in a way that conflicts with `fastapi-offline`'s approach, possibly due to a version mismatch.
  fix Ensure you are consistently instantiating `FastAPIOffline` and not directly manipulating FastAPI's internal documentation rendering. Check that both `fastapi-offline` and `fastapi` are reasonably up-to-date and compatible versions.

Warnings

• breaking Older Python versions are no longer supported or tested. Releases starting from v1.7.0 and v1.7.4 explicitly stopped testing on EOL Python versions (e.g., 3.7 and 3.9).
  Fix: Ensure your project uses Python 3.8 or newer. Upgrade your Python environment to a currently supported version.
• gotcha The `FastAPIOffline` constructor handles `docs_url`, `redoc_url`, `favicon_url`, and `static_url` parameters differently than a standard `FastAPI` app. Attempting to set these directly on the underlying `FastAPI` instance or expecting default FastAPI behavior for these specific URLs might lead to unexpected results.
  Fix: Customize `docs_url`, `redoc_url`, `favicon_url`, and `static_url` directly through the `FastAPIOffline` constructor. Other `FastAPI` parameters are passed through as expected.
• gotcha Compatibility issues may arise if `fastapi-offline` is significantly outdated compared to your `fastapi` version. `fastapi-offline`'s releases often include updates to the bundled Swagger UI and Redoc assets to track changes in FastAPI's behavior and dependencies.
  Fix: Always try to keep `fastapi-offline` updated to a version compatible with your `fastapi` installation. Check the release notes of `fastapi-offline` for any specific FastAPI version tracking information.

Install

• pip install fastapi-offline Install latest version

Imports

• FastAPIOffline
  wrong:

  from fastapi import FastAPI

  correct:

  from fastapi_offline import FastAPIOffline

  When using `fastapi-offline`, you should instantiate `FastAPIOffline` instead of `FastAPI` to enable offline documentation features.

Quickstart

This quickstart demonstrates how to create a basic FastAPI application using `FastAPIOffline`. Simply import `FastAPIOffline` and instantiate it instead of `FastAPI`. The interactive documentation (Swagger UI and ReDoc) will then be served from local assets, making them available offline. Any parameters passed to `FastAPIOffline()` (except `docs_url`, `redoc_url`, `favicon_url`, and `static_url`) are forwarded to the underlying `FastAPI` instance.

from fastapi_offline import FastAPIOffline
import uvicorn

app = FastAPIOffline(
    title="My Offline API",
    description="A simple API with offline docs"
)

@app.get("/")
async def read_root():
    return {"message": "Hello Offline World!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

# To run this app, save it as main.py and execute: uvicorn main:app --reload
# Then open http://127.0.0.1:8000/docs or http://127.0.0.1:8000/redoc in your browser.