13. OpenAPI Documentation

Chapter 13 of 18 · 15 min

KEY INSIGHT

OpenAPI specifications transform APIs from guesswork into self-documenting interfacesΓÇögenerated documentation reduces integration friction for every client. FastAPI automatically generates an OpenAPI 3.1 specification from route decorators, Pydantic models, and type hints. This specification drives automatic documentation UIs, client code generation, and API discovery tools. Maintaining accurate specifications requires ensuring types and examples reflect actual behavior. Route documentation begins with docstrings describing endpoint purposes, parameter meanings, and response schemas. Pydantic models include field descriptions that appear in the specification. Example values let clients understand expected formats without reading implementation code. ```python from fastapi import FastAPI from pydantic import BaseModel, Field from typing import Optional app = FastAPI(title="Inference API", version="1.0.0") class ChatCompletionRequest(BaseModel): model: str = Field( ..., description="Model identifier for completion generation", example="llama3.2:latest" ) messages: list[dict] = Field( ..., description="Conversation messages with role and content", example=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is API design?"} ] ) temperature: Optional[float] = Field( 0.7, description="Sampling temperature between 0 and 2", ge=0, le=2 ) max_tokens: Optional[int] = Field( 512, description="Maximum tokens to generate", ge=1, le=4096 ) class ChatCompletionResponse(BaseModel): model: str content: str tokens_used: int finish_reason: str @app.post( "/v1/chat/completions", response_model=ChatCompletionResponse, summary="Generate chat completions", description="Creates model-generated content from conversation context" ) async def create_chat_completion(request: ChatCompletionRequest): # Implementation pass ``` Enable request validation examples in the interactive documentation. Setting `openapi_url="/openapi.json"` makes the specification available for external tooling. Authentication schemes require definition in the OpenAPI spec to appear in the documentation UI. Test documentation by generating a client with `openapi-generator`. If generated code fails to compile or produces nonsensical types, the specification needs refinement. Client-driven validation catches specification gaps before they frustrate API consumers.

Local verification checkpoint

Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.

EXERCISE

Configure FastAPI to include examples in the OpenAPI specification using Pydantic's model_config. Verify examples appear in the Swagger UI by navigating to /docs and examining endpoint schemas.