OpenAPI & Interactive Docs

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Book(BaseModel):
    id: int
    title: str
    author: str
    year: int | None = None


BOOKS = [Book(id=1, title="Dune", author="Frank Herbert", year=1965)]


@app.get("/books")
def list_books(limit: int = 10) -> list[Book]:
    return BOOKS[:limit]


@app.get("/books/{book_id}")
def get_book(book_id: int) -> Book:
    return BOOKS[0]

{
  "openapi": "3.1.0",
  "info": {"title": "FastAPI", "version": "0.1.0"},
  "paths": {
    "/books": {
      "get": {
        "summary": "List Books",
        "operationId": "list_books_books_get",
        "parameters": [
          {"name": "limit", "in": "query", "required": false,
           "schema": {"type": "integer", "default": 10, "title": "Limit"}}
        ],
        "responses": {
          "200": {"description": "Successful Response",
                  "content": {"application/json": {"schema": {
                    "type": "array", "items": {"$ref": "#/components/schemas/Book"},
                    "title": "Response List Books Books Get"}}}},
          "422": {"description": "Validation Error",
                  "content": {"application/json": {"schema": {
                    "$ref": "#/components/schemas/HTTPValidationError"}}}}
        }
      }
    }
  },
  "components": {"schemas": {"Book": {"...": "..."}, "HTTPValidationError": {"...": "..."}}}
}

GET /openapi.json          200 application/json
GET /docs                  200 text/html; charset=utf-8     (Swagger UI)
GET /redoc                 200 text/html; charset=utf-8     (ReDoc)
GET /docs/oauth2-redirect  200 text/html; charset=utf-8     (helper for OAuth2 login from Swagger UI)

from typing import Annotated

from fastapi import Depends, FastAPI, Query
from fastapi.security import OAuth2PasswordBearer
from pydantic import BaseModel, Field

app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


class ReviewIn(BaseModel):
    rating: int = Field(ge=1, le=5, description="Stars from 1 to 5", examples=[4])
    text: str = Field(default="", max_length=2000, description="Optional free text")


@app.get("/books")
def search_books(
    q: Annotated[
        str | None,
        Query(
            title="Search text",
            description="Matches title and author, case-insensitive.",
            examples=["dune"],
            max_length=50,
        ),
    ] = None,
    sort: Annotated[str | None, Query(deprecated=True)] = None,
    debug: Annotated[bool, Query(include_in_schema=False)] = False,
) -> list[str]:
    return []


@app.post("/books/{book_id}/reviews", status_code=201)
def add_review(
    book_id: int,
    review: ReviewIn,
    token: Annotated[str, Depends(oauth2_scheme)],
) -> ReviewIn:
    return review

from fastapi import FastAPI

description = """
The **Bookshelf API** manages books, authors and reviews.

## Books

You can list, search and read books.

## Reviews

Readers can post reviews (_authentication required_).
"""

tags_metadata = [
    {
        "name": "books",
        "description": "Browse and manage the **catalog**.",
    },
    {
        "name": "reviews",
        "description": "Reader reviews, one list per book.",
        "externalDocs": {
            "description": "Review guidelines",
            "url": "https://bookshelf.example.com/guidelines",
        },
    },
]

app = FastAPI(
    title="Bookshelf API",
    summary="A small catalog of books, authors and reviews.",
    description=description,
    version="2.5.0",
    terms_of_service="https://bookshelf.example.com/terms/",
    contact={
        "name": "Bookshelf Support",
        "url": "https://bookshelf.example.com/contact/",
        "email": "support@bookshelf.example.com",
    },
    license_info={"name": "Apache 2.0", "identifier": "Apache-2.0"},
    openapi_tags=tags_metadata,
    openapi_external_docs={
        "description": "Developer portal",
        "url": "https://bookshelf.example.com/developers",
    },
    openapi_url="/api/v1/openapi.json",
    docs_url="/documentation",
    redoc_url=None,
)


@app.get("/books", tags=["books"])
def list_books() -> list[str]:
    return ["Dune"]


@app.get("/books/{book_id}/reviews", tags=["reviews"])
def list_reviews(book_id: int) -> list[str]:
    return []

{
  "openapi": "3.1.0",
  "info": {
    "title": "Bookshelf API",
    "summary": "A small catalog of books, authors and reviews.",
    "description": "\nThe **Bookshelf API** manages books, authors and reviews.\n\n## Books\n...",
    "termsOfService": "https://bookshelf.example.com/terms/",
    "contact": {
      "name": "Bookshelf Support",
      "url": "https://bookshelf.example.com/contact/",
      "email": "support@bookshelf.example.com"
    },
    "license": {"name": "Apache 2.0", "identifier": "Apache-2.0"},
    "version": "2.5.0"
  },
  "tags": [
    {"name": "books", "description": "Browse and manage the **catalog**."},
    {"name": "reviews", "description": "Reader reviews, one list per book.",
     "externalDocs": {"description": "Review guidelines",
                      "url": "https://bookshelf.example.com/guidelines"}}
  ],
  "externalDocs": {"description": "Developer portal",
                   "url": "https://bookshelf.example.com/developers"}
}

from enum import Enum

from fastapi import APIRouter, FastAPI
from pydantic import BaseModel


class Tags(Enum):
    books = "books"
    authors = "authors"


class BookIn(BaseModel):
    title: str
    author: str


app = FastAPI()


@app.post(
    "/books",
    tags=[Tags.books],
    summary="Add a book",
    response_description="The book as stored in the catalog",
    operation_id="add_book",
    status_code=201,
)
def add_book(book: BookIn) -> BookIn:
    """
    Add a book to the catalog.

    - **title**: required, shown in search results
    - **author**: required, the display name of the author

    The call is *idempotent* per title and author.
    \f
    :param book: Internal note for Sphinx; not part of the OpenAPI document.
    """
    return book


@app.get("/books/legacy", tags=[Tags.books], deprecated=True)
def list_books_legacy() -> list[BookIn]:
    return []


@app.get("/health", include_in_schema=False)
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/books/audit", openapi_extra={"x-internal-owner": "catalog-team"})
def audit_books() -> list[str]:
    return []


authors = APIRouter(prefix="/authors", tags=[Tags.authors])


@authors.get("")
def list_authors() -> list[str]:
    return ["Frank Herbert"]


@authors.get("/search", deprecated=False)
def search_authors(q: str) -> list[str]:
    return []


app.include_router(authors, deprecated=True)

"/books": {
  "post": {
    "tags": ["books"],
    "summary": "Add a book",
    "description": "Add a book to the catalog.\n\n- **title**: required, shown in search results\n- **author**: required, the display name of the author\n\nThe call is *idempotent* per title and author.",
    "operationId": "add_book",
    "requestBody": {"required": true, "content": {"application/json": {
      "schema": {"$ref": "#/components/schemas/BookIn"}}}},
    "responses": {
      "201": {"description": "The book as stored in the catalog",
              "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BookIn"}}}},
      "422": {"description": "Validation Error", "content": {"application/json": {"schema": {
        "$ref": "#/components/schemas/HTTPValidationError"}}}}
    }
  }
}

import csv
import io

import yaml
from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, ValidationError

app = FastAPI()


class BookIn(BaseModel):
    title: str
    author: str


@app.post(
    "/books/import",
    openapi_extra={
        "requestBody": {
            "required": True,
            "content": {
                "text/csv": {
                    "schema": {"type": "string"},
                    "example": "title,author\nDune,Frank Herbert\n",
                }
            },
        }
    },
)
async def import_books(request: Request) -> dict[str, int]:
    raw = (await request.body()).decode()
    rows = list(csv.DictReader(io.StringIO(raw)))
    return {"imported": len(rows)}


@app.post(
    "/books/yaml",
    openapi_extra={
        "requestBody": {
            "required": True,
            "content": {"application/x-yaml": {"schema": BookIn.model_json_schema()}},
        }
    },
)
async def add_book_yaml(request: Request) -> BookIn:
    try:
        data = yaml.safe_load(await request.body())
        return BookIn.model_validate(data)
    except (yaml.YAMLError, ValidationError) as exc:
        raise HTTPException(status_code=422, detail="Invalid book document") from exc

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel, ConfigDict

app = FastAPI()


class BookIn(BaseModel):
    title: str
    author: str
    year: int | None = None

    model_config = ConfigDict(
        json_schema_extra={
            "examples": [{"title": "Dune", "author": "Frank Herbert", "year": 1965}]
        }
    )


@app.post("/books")
def add_book(
    book: Annotated[
        BookIn,
        Body(
            openapi_examples={
                "classic": {
                    "summary": "A classic",
                    "description": "Title, author and year.",
                    "value": {"title": "Dune", "author": "Frank Herbert", "year": 1965},
                },
                "minimal": {
                    "summary": "Only required fields",
                    "value": {"title": "Untitled", "author": "Unknown"},
                },
            },
        ),
    ],
) -> BookIn:
    return book

from fastapi import APIRouter, FastAPI
from fastapi.responses import JSONResponse, Response
from pydantic import BaseModel


class Book(BaseModel):
    id: int
    title: str


class Message(BaseModel):
    message: str


common_responses = {
    401: {"model": Message, "description": "Missing or invalid credentials"},
    403: {"description": "Not enough privileges"},
}

app = FastAPI(responses={500: {"model": Message, "description": "Unexpected error"}})
router = APIRouter(prefix="/books", responses={429: {"description": "Rate limited"}})


@router.get(
    "/{book_id}",
    response_model=Book,
    responses={
        **common_responses,
        404: {"model": Message, "description": "The book was not found"},
        200: {
            "description": "The book",
            "content": {
                "application/json": {"example": {"id": 1, "title": "Dune"}},
            },
        },
    },
)
def get_book(book_id: int):
    if book_id == 1:
        return {"id": 1, "title": "Dune"}
    return JSONResponse(status_code=404, content={"message": "Book not found"})


@router.get(
    "/{book_id}/cover",
    response_class=Response,
    responses={
        200: {"content": {"image/png": {}}, "description": "The cover image"},
        404: {"model": Message},
    },
)
def get_cover(book_id: int):
    return Response(content=b"\x89PNG\r\n\x1a\n", media_type="image/png")


app.include_router(router)

GET /books/{book_id}
  200  The book                          application/json   (with the example)
  500  Unexpected error                  application/json   (from the application)
  429  Rate limited                      -                  (from the router)
  401  Missing or invalid credentials    application/json   (shared dict)
  403  Not enough privileges             -                  (shared dict)
  404  The book was not found            application/json
  422  Validation Error                  application/json   (added by FastAPI)

GET /books/{book_id}/cover
  200  The cover image                   image/png
  500, 429                               as above
  404  Not Found                        application/json   (model without description)
  422  Validation Error                  application/json

from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, computed_field

app = FastAPI()  # separate_input_output_schemas=True is the default


class Book(BaseModel):
    title: str
    year: int

    @computed_field
    @property
    def label(self) -> str:
        return f"{self.title} ({self.year})"


class Review(BaseModel):
    model_config = ConfigDict(json_schema_serialization_defaults_required=True)

    rating: int
    tags: list[str] = []


@app.post("/books")
def add_book(book: Book) -> Book:
    return book


@app.post("/reviews")
def add_review(review: Review) -> Review:
    return review


single = FastAPI(separate_input_output_schemas=False)
single.post("/books")(add_book)
single.post("/reviews")(add_review)

from datetime import datetime

import httpx
from fastapi import APIRouter, BackgroundTasks, FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Subscription(BaseModel):
    id: str
    genre: str


class ReviewEvent(BaseModel):
    book_id: int
    rating: int
    posted_at: datetime


class EventReceived(BaseModel):
    ok: bool


callback_router = APIRouter()


@callback_router.post(
    "{$callback_url}/reviews/{$request.body.id}", response_model=EventReceived
)
def review_notification(body: ReviewEvent):
    pass


async def notify(callback_url: str, subscription_id: str, event: ReviewEvent) -> None:
    async with httpx.AsyncClient() as client:
        await client.post(
            f"{callback_url}/reviews/{subscription_id}",
            content=event.model_dump_json(),
            headers={"Content-Type": "application/json"},
        )


@app.post("/subscriptions", callbacks=callback_router.routes)
def subscribe(
    subscription: Subscription,
    callback_url: HttpUrl,
    background_tasks: BackgroundTasks,
) -> dict[str, str]:
    """Subscribe to new reviews in a genre; reviews are POSTed to the callback URL."""
    event = ReviewEvent(book_id=1, rating=5, posted_at=datetime(2026, 10, 2, 9, 30))
    background_tasks.add_task(notify, str(callback_url).rstrip("/"), subscription.id, event)
    return {"status": "subscribed"}


@app.webhooks.post("new-review")
def new_review(body: ReviewEvent):
    """
    Sent to every registered endpoint when a review is posted. Reply with any
    2xx status within five seconds to acknowledge it.
    """

from fastapi import FastAPI
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    openapi_url: str = "/openapi.json"


settings = Settings()
app = FastAPI(openapi_url=settings.openapi_url)


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

OPENAPI_URL= uvicorn ex09_conditional:app
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/openapi.json   # 404
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/docs           # 404
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/               # 200

import secrets
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.security import HTTPBasic, HTTPBasicCredentials
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    docs_user: str
    docs_password: str


settings = Settings()
basic = HTTPBasic()


def docs_access(credentials: Annotated[HTTPBasicCredentials, Depends(basic)]) -> None:
    user_ok = secrets.compare_digest(credentials.username.encode(), settings.docs_user.encode())
    password_ok = secrets.compare_digest(credentials.password.encode(), settings.docs_password.encode())
    if not (user_ok and password_ok):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )


app = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)


@app.get("/books")
def list_books() -> list[str]:
    return ["Dune"]


@app.get("/internal/openapi.json", include_in_schema=False, dependencies=[Depends(docs_access)])
def internal_openapi() -> dict:
    return app.openapi()


@app.get("/internal/docs", include_in_schema=False, dependencies=[Depends(docs_access)])
def internal_docs():
    return get_swagger_ui_html(
        openapi_url="/internal/openapi.json", title=f"{app.title} - Swagger UI"
    )

curl -si http://127.0.0.1:8000/internal/docs

HTTP/1.1 401 Unauthorized
www-authenticate: Basic
content-type: application/json

{"detail":"Not authenticated"}

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

app = FastAPI(title="Bookshelf API", version="2.5.0")


@app.get("/books")
def list_books() -> list[str]:
    return ["Dune"]


def custom_openapi() -> dict:
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title=app.title,
        version=app.version,
        openapi_version=app.openapi_version,
        summary="Catalog of books, authors and reviews",
        description=app.description,
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://bookshelf.example.com/logo.png"}
    schema["externalDocs"] = {
        "description": "Developer portal",
        "url": "https://bookshelf.example.com/developers",
    }
    app.openapi_schema = schema
    return app.openapi_schema


app.openapi = custom_openapi

{
  "openapi": "3.1.0",
  "info": {
    "title": "Bookshelf API",
    "summary": "Catalog of books, authors and reviews",
    "version": "2.5.0",
    "x-logo": {"url": "https://bookshelf.example.com/logo.png"}
  },
  "externalDocs": {"description": "Developer portal",
                   "url": "https://bookshelf.example.com/developers"}
}

from fastapi import FastAPI

app = FastAPI(
    swagger_ui_parameters={
        "docExpansion": "none",
        "defaultModelsExpandDepth": -1,
        "persistAuthorization": True,
        "displayRequestDuration": True,
        "filter": True,
        "operationsSorter": "alpha",
        "syntaxHighlight": {"theme": "obsidian"},
        "deepLinking": False,
    },
    swagger_ui_init_oauth={
        "clientId": "bookshelf-docs",
        "appName": "Bookshelf API docs",
        "usePkceWithAuthorizationCodeGrant": True,
    },
)


@app.get("/books")
def list_books() -> list[str]:
    return ["Dune"]

SwaggerUIBundle({
    url: '/openapi.json',
    "dom_id": "#swagger-ui",
    "layout": "BaseLayout",
    "deepLinking": false,
    "showExtensions": true,
    "showCommonExtensions": true,
    "docExpansion": "none",
    "defaultModelsExpandDepth": -1,
    "persistAuthorization": true,
    "displayRequestDuration": true,
    "filter": true,
    "operationsSorter": "alpha",
    "syntaxHighlight": {"theme": "obsidian"},
    oauth2RedirectUrl: window.location.origin + '/docs/oauth2-redirect',
    presets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ],
})
ui.initOAuth({"clientId": "bookshelf-docs", "appName": "Bookshelf API docs", "usePkceWithAuthorizationCodeGrant": true})

from pathlib import Path

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles

STATIC = Path(__file__).parent / "static"

app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/static", StaticFiles(directory=STATIC), name="static")


@app.get("/docs", include_in_schema=False)
async def swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=f"{app.title} - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
        swagger_favicon_url="/static/favicon.png",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=f"{app.title} - ReDoc",
        redoc_js_url="/static/redoc.standalone.js",
        redoc_favicon_url="/static/favicon.png",
        with_google_fonts=False,
    )


@app.get("/books")
def list_books() -> list[str]:
    return ["Dune"]

npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client

from fastapi import FastAPI
from fastapi.routing import APIRoute
from pydantic import BaseModel


def unique_id(route: APIRoute) -> str:
    return f"{route.tags[0]}-{route.name}"


app = FastAPI(generate_unique_id_function=unique_id)


class Book(BaseModel):
    title: str


@app.get("/books", tags=["books"])
def list_books() -> list[Book]:
    return []


@app.post("/books", tags=["books"])
def create_book(book: Book) -> Book:
    return book


@app.get("/authors", tags=["authors"])
def list_authors() -> list[str]:
    return []

import json
import sys
from pathlib import Path

from ex13_clients import app


def main(target: str, check: bool = False) -> int:
    document = json.dumps(app.openapi(), indent=2, sort_keys=True) + "\n"
    path = Path(target)
    if check:
        return 0 if path.exists() and path.read_text() == document else 1
    path.write_text(document)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1], check="--check" in sys.argv))

from fastapi.testclient import TestClient

from ex13_clients import app

HTTP_METHODS = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}


def operations(schema: dict):
    for path, item in schema["paths"].items():
        for method, operation in item.items():
            if method in HTTP_METHODS:
                yield path, method, operation


def test_openapi_document_is_served_and_tidy() -> None:
    response = TestClient(app).get("/openapi.json")
    assert response.status_code == 200
    schema = response.json()
    assert schema["openapi"].startswith("3.1")

    operation_ids = [op["operationId"] for _, _, op in operations(schema)]
    assert len(operation_ids) == len(set(operation_ids))
    for path, method, operation in operations(schema):
        assert operation.get("tags"), f"{method.upper()} {path} has no tag"

schemathesis run http://127.0.0.1:8000/openapi.json --max-examples 20