API Documentation

Flasgo generates OpenAPI 3.2.0 with an explicit JSON Schema 2020-12 dialect and can serve a built-in Swagger UI. Specification generation is always available; serving the two documentation endpoints is disabled by default.

Generated contract

The generator uses registered routes and the same compiled endpoint plans used at runtime. It documents:

• Flask-style path converters and typed path parameters, with untyped <name> segments documented using the handler’s annotated type (or string when unannotated);
• Body(), Query(), Header(), Cookie(), and Form() bindings;
• parameters supplied by Depends() providers;
• reusable dataclass request and response schemas;
• request media types and structured 422 validation responses;
• authorization security schemes, required scopes or roles, and 401/403 responses;
• applicable framework responses such as 413, 415, and 429;
• route docstrings, return annotations, and root API_SERVERS entries.

The documented responses match runtime behavior. A handler annotated -> None is documented as 204 No Content with no response body. str and bytes return annotations document text/plain, the content type Flasgo sends for both. set[T] schemas declare uniqueItems. The first docstring line becomes the operation summary; the remaining text becomes the description with its paragraph breaks and indentation preserved. Operation IDs contain only [A-Za-z0-9_], with other characters replaced by underscores so client generators accept them.

Standard operations, including OpenAPI 3.2 QUERY, use normal Path Item fields. Other valid HTTP methods are emitted through additionalOperations.

spec = app.openapi_spec()
assert spec["openapi"] == "3.2.0"

See Request Data and Dependencies for the runtime binding model that feeds the contract.

Response and dependency contracts

The generator also documents inherited blueprint permissions, standalone route/group dependency inputs, and explicit response_model= schemas. Underscore-prefixed dataclass fields are excluded from schemas and output. Runtime enforcement requires response_model=; a return annotation alone remains descriptive. Tuple response models are rejected at registration because a returned tuple is read as (body, status); use a list or dataclass instead. See Response Contracts.

A return annotation of StreamingResponse, EventSourceResponse, or NDJSONResponse advertises application/octet-stream, text/event-stream, or application/x-ndjson, respectively. An item_model= or custom media type chosen inside a handler is runtime configuration and cannot be inferred into the schema. See Streaming Responses.

The generator unwraps Annotated[T, ...] return types before selecting the media type. For example, Annotated[EventSourceResponse, "progress events"] still documents text/event-stream, and Annotated[str, "plain text"] documents text/plain. This metadata does not enable runtime response validation.

Dependency overrides are local to execution and do not mutate the published OpenAPI contract.

Built-in endpoints

When ENABLE_DOCS=True, Flasgo reserves two endpoints before normal route matching:

Endpoint	Default path	Setting
Swagger UI	/docs	DOCS_PATH
OpenAPI JSON	/openapi.json	OPENAPI_PATH

They accept only GET and HEAD; other methods receive 405 Method Not Allowed. When docs are disabled, the paths fall through to normal route matching. Both paths are relative to the application’s mount point: under an ASGI root_path such as /api, Swagger UI requests the document from /api/openapi.json. The embedded spec URL escapes <, >, and &, so an unusual OPENAPI_PATH cannot close the page’s inline script.

Protecting the docs

Use DOCS_AUTH_BACKEND to apply an existing authentication backend to both the UI and the JSON document:

import hmac
import os

from flasgo import Flasgo, User, bearer_token_backend

docs_token = os.environ["FLASGO_DOCS_TOKEN"]


def validate_docs_token(token: str) -> User | None:
    if hmac.compare_digest(token, docs_token):
        return User(id="docs", is_authenticated=True)
    return None


app = Flasgo(
    settings={
        "ENABLE_DOCS": True,
        "DOCS_AUTH_BACKEND": "docs",
        "DOCS_PATH": "/api-docs",
        "OPENAPI_PATH": "/api/openapi.json",
        "API_TITLE": "Example API",
        "API_VERSION": "1.0.0",
        "API_DESCRIPTION": "Internal service API.",
        "API_SERVERS": ["https://api.example.com"],
    }
)

app.register_auth_backend(
    "docs",
    bearer_token_backend(validate_docs_token),
)

The configured backend must be registered before the application is checked or serves the endpoints. Authentication failures are subject to the normal security-failure limiter.

Authentication metadata

bearer_token_backend() and jwt_backend() provide accurate HTTP security metadata automatically. Application-owned backends may declare a local OpenAPI Security Scheme Object at registration:

app.register_auth_backend(
    "deviceOAuth",
    backend,
    openapi_scheme={
        "type": "oauth2",
        "oauth2MetadataUrl": (
            "https://identity.example.com/"
            ".well-known/oauth-authorization-server"
        ),
        "flows": {
            "deviceAuthorization": {
                "deviceAuthorizationUrl": (
                    "https://identity.example.com/device"
                ),
                "tokenUrl": "https://identity.example.com/token",
                "scopes": {"read": "Read account data"},
            }
        },
    },
)

Flasgo validates and copies the metadata. OAuth and OpenID URLs must use HTTPS; supported extension keys begin with x-; and external $ref values are rejected. The metadata documents credentials accepted by your backend, but it does not implement an OAuth authorization server.

Generate without serving

Print or atomically write a deterministic artifact:

uv run flasgo openapi app.py
uv run flasgo openapi app.py --output openapi.json
uv run flasgo check app.py

--output replaces an existing file atomically and keeps its permissions; a new file uses the process umask.

The check catches route conflicts, missing authentication backends, and internal endpoint conflicts without starting a server.

Swagger UI security

The built-in UI uses an exact version of the Swagger distribution with subresource-integrity hashes. Query-driven configuration and remote validation are disabled. Inline script and style content runs with a rotating per-response CSP nonce rather than unsafe-inline.

Even with those controls, expose API metadata deliberately. Prefer a controlled development or staging environment, use DOCS_AUTH_BACKEND whenever the endpoints are reachable beyond a trusted local environment, and review generated schemas for information your application should not disclose.

Sources:

• README.md
• flasgo/openapi.py
• flasgo/auth.py