specbook-fastapi

Serves the Specbook UI for your FastAPI app's OpenAPI document. It reads the document in the browser and lets a visitor send each request: against mock responses built from the document's examples, or live against your API. It runs on your app's own origin, so there is no CORS to configure and the visitor's cookies are sent.

See the Specbook docs for what else it can do: requests with checks, flows, tests that run in CI, and a portal for QA.

The package only returns an HTML page that loads the viewer, so it adds nothing to your app but one route.

Installation

pip install specbook-fastapi
# or
uv add specbook-fastapi

Python 3.10 or newer, and FastAPI.

Usage

Serve the viewer at /specbook for the app's own OpenAPI document:

from fastapi import FastAPI
from specbook_fastapi import add_specbook

app = FastAPI()
add_specbook(app)  # the viewer is at /specbook

To use it instead of FastAPI's own docs page, turn that off and take its route:

app = FastAPI(docs_url=None, redoc_url=None)
add_specbook(app, route="/docs")

The document's address and the page title come from the app (app.openapi_url, with the request's root_path in front of it, so it works behind a prefix or a proxy, and app.title). The route is left out of the OpenAPI document.

Your own route

get_specbook_html returns an HTMLResponse, for when you want to set the route up yourself:

from fastapi import FastAPI
from specbook_fastapi import get_specbook_html

app = FastAPI(docs_url=None)


@app.get("/docs", include_in_schema=False)
async def docs():
    return get_specbook_html(openapi_url=app.openapi_url, title=f"{app.title} docs", default_env="live")

Options

add_specbook takes route and include_in_schema, and passes every other keyword argument on to get_specbook_html.

The viewer's own settings (default_env, the page title, the Content-Security-Policy it needs) are described in the embed reference.

The specbook host is the newest deployed build of the v1 line, so fixes reach your app without a new release of this package. A breaking change to the viewer would ship as /v2/. The npm host is an immutable release of @specbook/ui; pin version to hold it still.

Content-Security-Policy

The page has no inline script. The JSON that configures the viewer is data, so it needs no nonce, and the one module script takes nonce when your policy uses nonces.

Privacy

The viewer runs no analytics or tracking script, and your document and your API's responses stay in the visitor's browser; nothing is sent to Specbook. Loading the script from ui.specbook.dev or jsDelivr means that host sees the visitor's IP address and the file requests, as any CDN does; serve the viewer yourself to avoid that.

The overview shows a small "Powered by Specbook" link. It points to docs.specbook.dev with your site's hostname in the address, and the Specbook docs site uses Cloudflare Web Analytics.

Serving the viewer yourself

Every Specbook release carries the viewer's files as specbook-viewer-<version>.zip (MIT, with its third-party licence notices) on its GitHub release, and @specbook/ui on npm ships the same files in dist-viewer/. Unpack them into a folder, serve it from your app and point src at it, so nothing is loaded from another host:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from specbook_fastapi import add_specbook

app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/specbook-viewer", StaticFiles(directory="specbook-viewer"), name="specbook-viewer")
add_specbook(app, route="/docs", src="/specbook-viewer/specbook.js")

Author

Maintained by the Specbook team. Issues are welcome at specbook-dev/specbook.

License

MIT