FastAPI OpenAPI & Dokumentation

6 Kernkonzepte
Die wichtigsten Konzepte für OpenAPI-Dokumentation in FastAPI: Metadata · Tags · Response Model · OpenAPI Schema · Custom Documentation · Security FastAPI generiert automatisch eine interaktive OpenAPI-Dokumentation. Diese Cheatsheet zeigt, wie Sie die Dokumentation anpassen, strukturieren und erweitern können.

Metadata – API-Informationen definieren

title · description · version · contact · license
app = FastAPI( title="User Management API", description="REST API für Benutzerverwaltung", version="2.0.0" )

Metadata definiert die Basisinformationen Ihrer API – Titel, Beschreibung, Version, Kontakt und Lizenz – die in der OpenAPI-Dokumentation angezeigt werden.

Beispiele
# Vollständige API-Metadaten
app = FastAPI(
title="E-Commerce API",
description="""
Diese API ermöglicht die Verwaltung von Produkten,
Bestellungen und Benutzern in einem Online-Shop.
Sie unterstützt CRUD-Operationen und Authentifizierung.
""",
version="1.0.0",
contact={
"name": "Support Team",
"email": "support@example.com",
"url": "https://example.com/support"
},
license_info={
"name": "MIT License",
"url": "https://opensource.org/licenses/MIT"
},
terms_of_service="https://example.com/terms"
)
# OpenAPI-URLs deaktivieren (z.B. für Production)
app = FastAPI(docs_url=None, redoc_url=None)
# OpenAPI-URLs anpassen
app = FastAPI(docs_url="/swagger", redoc_url="/api-docs")
Tipp: Nutzen Sie mehrzeilige Strings ("""...""") für ausführliche Beschreibungen – sie werden in der OpenAPI-Dokumentation korrekt formatiert.

Tags – Endpunkte gruppieren

tags · Tag · Tag metadata
@app.get("/users", tags=["Users"]) async def get_users(): return [{"id": 1, "name": "Anna"}]

Tags gruppieren zusammengehörige Endpunkte in der OpenAPI-Dokumentation – das verbessert die Übersichtlichkeit und Navigation.

Beispiele
# Einfache Tags
@app.get("/users", tags=["Users"])
async def get_users(): return []
# Mehrere Tags pro Endpunkt
@app.post("/users", tags=["Users", "Admin"])
async def create_user(): return {}
# Tag-Metadaten (Beschreibung für Tag)
tags_metadata = [
{
"name": "Users",
"description": "Benutzerverwaltung – CRUD-Operationen",
},
{
"name": "Products",
"description": "Produktverwaltung",
"externalDocs": {
"description": "Detaillierte Produktdokumentation",
"url": "https://example.com/products/docs"
}
}
]
# Tags in FastAPI registrieren
app = FastAPI(openapi_tags=tags_metadata)
# Tags als Enum verwenden
from enum import Enum
class Tags(Enum):
USERS = "Users"
PRODUCTS = "Products"
ORDERS = "Orders"
# Verwendung
@app.get("/users", tags=[Tags.USERS.value])
Tipp: Verwenden Sie konsistente Tags über Ihre Endpunkte hinweg. Tag-Metadaten mit Beschreibungen helfen Nutzern, Ihre API zu verstehen.

Response Model – Dokumentation der Antwortstruktur

response_model · response_model_include · response_model_exclude
class UserResponse(BaseModel): id: int name: str email: str @app.get("/users", response_model=UserResponse)

Response Model definiert die Struktur der API-Antwort in der OpenAPI-Dokumentation und filtert gleichzeitig die tatsächliche Antwort.

Beispiele
# Modelle für Requests und Responses
class UserCreate(BaseModel):
name: str
email: str
password: str
class UserResponse(BaseModel):
id: int
name: str
email: str
created_at: datetime
@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
# Password wird nicht in der Antwort erscheinen
return {
"id": 1,
"name": user.name,
"email": user.email,
"created_at": datetime.utcnow()
}
# Felder aus der Antwort ausschließen
@app.get("/users", response_model=UserResponse, response_model_exclude={"created_at"})
async def get_users():
return [{"id": 1, "name": "Anna", "email": "a@b.com", "created_at": datetime.utcnow()}]
# Nur bestimmte Felder in der Antwort
@app.get("/users/minimal", response_model=UserResponse, response_model_include={"id", "name"})
async def get_users_minimal():
return [{"id": 1, "name": "Anna"}]
# response_model für Listen
from typing import List
@app.get("/users/all", response_model=List[UserResponse])
async def get_all_users():
return []
Tipp: Definieren Sie separate Request- und Response-Modelle – das verhindert, dass sensible Felder (z.B. Passwörter) in der API-Dokumentation erscheinen.

OpenAPI Schema – Erweiterung & Anpassung

get_openapi · openapi_extra · extensions
from fastapi.openapi.utils import get_openapi openapi_schema = get_openapi( title="Custom API", version="1.0", routes=app.routes )

OpenAPI Schema kann individuell angepasst werden – z.B. um eigene Felder hinzuzufügen, das Schema zu erweitern oder die Dokumentation zu optimieren.

Beispiele
# OpenAPI Schema überschreiben
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Meine API",
version="1.0.0",
description="Benutzerdefinierte API",
routes=app.routes
)
# Eigene Felder hinzufügen
openapi_schema["info"]["x-custom-field"] = "Custom Value"
app.openapi_schema = openapi_schema
return app.openapi_schema
# Registrierung
app.openapi = custom_openapi
# openapi_extra für Endpunkt
@app.get("/special", openapi_extra={"x-special": "Wert"})
async def special_endpoint():
return {}
# OpenAPI-Schema als JSON ausgeben
import json
@app.get("/openapi.json")
async def get_openapi_json():
return JSONResponse(content=app.openapi())
Tipp: Die manuelle Anpassung des OpenAPI-Schemas ist nützlich, wenn Sie proprietäre Erweiterungen oder zusätzliche Metadaten für Ihre API-Dokumentation benötigen.

Dokumentation – Benutzerdefinierte Beschreibungen

Docstring · description · response_description
@app.get("/users", description="Listet alle Benutzer auf") async def get_users(): """ Gibt eine Liste aller Benutzer zurück. """

Benutzerdefinierte Dokumentation verbessert die Lesbarkeit Ihrer API. Nutzen Sie Docstrings, Parameterbeschreibungen und Beispiele für eine optimale Entwicklererfahrung.

Beispiele
@app.get("/users/{user_id}",
description="Ruft einen Benutzer anhand der ID ab",
response_description="Benutzerdaten",
summary="Benutzer abrufen"
)
async def get_user(user_id: int):
"""
Ruft einen Benutzer anhand seiner ID ab.
- **user_id**: Eindeutige ID des Benutzers
- **returns**: Benutzerobjekt mit id, name und email
- **raises**: 404 wenn Benutzer nicht existiert
"""
return {"id": user_id, "name": "Anna"}
# Parameter-Dokumentation mit Field
class UserCreate(BaseModel):
name: str = Field(..., description="Vollständiger Name des Benutzers")
email: str = Field(..., description="E-Mail-Adresse (muss eindeutig sein)")
age: int = Field(18, description="Alter (optional, Standard: 18)")
# Beispiele in der Dokumentation
from pydantic import Field
class UserCreate(BaseModel):
name: str = Field(..., example="Anna Schmidt")
email: str = Field(..., example="anna@example.com")
age: int = Field(18, example=30)
Tipp: Nutzen Sie Docstrings für ausführliche Endpunkt-Beschreibungen. FastAPI extrahiert sie automatisch und zeigt sie in der Swagger UI an.

Sicherheit – Authentifizierung in der Dokumentation

security · OAuth2 · API Key · JWT
from fastapi.security import OAuth2PasswordBearer, APIKeyHeader oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/login") @app.get("/protected", dependencies=[Depends(oauth2_scheme)])

Sicherheitsschemas werden in der OpenAPI-Dokumentation angezeigt – so können Entwickler sehen, welche Authentifizierungsmethode für einen Endpunkt erforderlich ist.

Beispiele
# OAuth2 mit Password Flow
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")
@app.post("/token")
async def login(username: str = Form(), password: str = Form()):
# Token erstellen
return {"access_token": "token", "token_type": "bearer"}
# Geschützter Endpunkt
@app.get("/protected")
async def protected_endpoint(token: str = Depends(oauth2_scheme)):
return {"message": "Geschützt"}
# API Key Security
from fastapi.security import APIKeyHeader
api_key_header = APIKeyHeader(name="X-API-Key")
@app.get("/api-key-protected")
async def api_key_protected(api_key: str = Depends(api_key_header)):
return {"message": "API Key geschützt"}
# Benutzerdefinierte Security mit OpenAPI-Integration
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
security = HTTPBearer()
@app.get("/bearer-protected")
async def bearer_protected(credentials: HTTPAuthorizationCredentials = Depends(security)):
return {"token": credentials.credentials}
# Globale Security für alle Endpunkte
app = FastAPI(dependencies=[Depends(oauth2_scheme)])
# Security in der OpenAPI-Dokumentation anzeigen
app.openapi = custom_openapi # siehe vorherige Karte
Tipp: FastAPI integriert Security-Schemas automatisch in die OpenAPI-Dokumentation – so können Entwickler Endpunkte direkt in der Swagger UI testen.

FastAPI OpenAPI im Überblick

/docs Swagger UI
Interaktive API-Dokumentation
/redoc ReDoc
Alternative API-Dokumentation
tags Gruppierung
Endpunkte organisieren
response_model Antwortstruktur
Dokumentation & Filterung
Docstring Beschreibungen
Parameter, Beispiele
security Authentifizierung
OAuth2, API Key, JWT

Quick Summary

title
Metadata
tags
Gruppierung
response_model
Antwortstruktur
openapi
Schema
Docstring
Dokumentation
security
Sicherheit
@app.get("/users", tags=["Users"]) · response_model=UserResponse · description="Listet alle Benutzer auf"
Alle Cheatsheets Impressum Datenschutz
Zum Drucken
© ITGrundlagen.com · FastAPI OpenAPI Cheatsheet · Befehlsübersicht · Schnellreferenz