FastAPI Interaktive API-Dokumentation

FastAPI generiert automatisch interaktive API-Dokumentation basierend auf Typannotationen im Code und bietet standardmäßig zwei Oberflächen: Swagger UI und ReDoc. Entwickler können APIs direkt in der Dokumentation testen, ohne zusätzliche Tools.

Zugriff auf die API-Dokumentation

Nach dem Ausführen der FastAPI-Anwendung besuchen Sie die folgende Adresse, um die Dokumentation anzuzeigen:

AdresseDokumenttypFunktionen
http://127.0.0.1:8000/docsSwagger UIInteraktives Testen: Klicken Sie auf "Try it out", um Anfragen zu senden.
http://127.0.0.1:8000/redocReDocGute Leseerfahrung, geeignet zum Durchsuchen und Nachschlagen von API-Definitionen.
http://127.0.0.1:8000/openapi.jsonOpenAPI JSONUnverarbeitete OpenAPI-Spezifikation als JSON, verfügbar für die Nutzung durch Tools.

Swagger UI

Swagger UI bietet eine intuitive Benutzeroberfläche, um APIs direkt im Browser zu testen:

Schritte zum Testen der API

  1. Klicken Sie auf die Route, die Sie testen möchten, um ihre Details zu erweitern
  2. Klicken Sie auf die Schaltfläche"Try it out"Button
  3. Parameterwerte eingeben
  4. Klicken Sie auf die Schaltfläche"Execute", um die Anfrage zu senden
  5. Antwortergebnisse anzeigen

ReDoc

ReDoc konzentriert sich auf die Lesbarkeit von Dokumenten und eignet sich zum Durchsuchen von API-Definitionen:

OpenAPI-Spezifikation

FastAPI-NutzungOpenAPIDer Standard konvertiert APIs in "Schemas". Besuchen Siehttp://127.0.0.1:8000/openapi.jsonSie können das rohe OpenAPI-JSON anzeigen:

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

Zweck der OpenAPI-Spezifikation:

  • Betreibt die Dokumentationssysteme Swagger UI und ReDoc
  • Automatische Generierung von Client-Code in verschiedenen Sprachen
  • Integration mit API-Testtools (wie Postman)
  • Kompatibel mit einer großen Anzahl von Drittanbieter-Tools und -Plattformen

API-Dokumentationsinformationen anpassen

Beim Erstellen einer FastAPI-Instanz können Sie die Metadaten der Dokumentation anpassen:

Beispiel

from fastapi import FastAPI

app = FastAPI(
    title="Meine API",                    # API-Titel
    description="Dies ist eine Beispiel-API, die Anpassungsfunktionen für die Dokumentation demonstriert",  # API-Beschreibung
    version="1.0.0",                    # API-Version
    terms_of_service="http://example.com/terms/",  # URL der Nutzungsbedingungen
    contact={                           # Kontaktinformationen
        "name": "Entwickler",
        "url": "http://example.com/contact/",
        "email": "[email protected]",
    },
    license_info={                      # Lizenzinformationen
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

Dokumentationsinformationen für Routen hinzufügen

Sie können detaillierte Dokumentationsinformationen für jede Route in Dekoratoren und Funktionen hinzufügen:

Beispiel

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary="Produktinformationen abrufen",              # Kurze Zusammenfassung
    description="Detaillierte Produktinformationen anhand der Produkt-ID abrufen",  # Detaillierte Beschreibung
    response_description=Produktinformationsobjekt,   # Antwortbeschreibung
    tags=["Produktverwaltung"],                   # Gruppen-Tags
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="Produkt-ID")],
    q: Annotated[str | None, Query(description=“Suchbegriffe”)] = Keine,
):
    """
Produktinformationen abrufen:

- **item_id**: Die eindeutige Kennung des Produkts.
- **q**: optionaler Suchbegriff
    """
    return {"item_id": item_id, "q": q}

Beschreibung des Dokumentationsparameters:

ParameterPositionBeschreibung
summaryDekoratorKurze Zusammenfassung der Route, angezeigt in der Routenliste.
descriptionDekoratorDetaillierte Beschreibung der Route, unterstützt Markdown.
response_descriptionDekoratorBeschreibung der Antwort
tagsDekoratorRoutengruppierung, in der Dokumentation nach Tag-Kategorien angezeigt.
DocstringFunktionskörperFunktions-Docstrings werden als Beschreibungen angezeigt.

Wenn beide gleichzeitig gesetzt sinddescriptionund der Docstring der Funktion,descriptionHat Vorrang. Docstrings unterstützen das Markdown-Format und eignen sich zum Verfassen längerer Erklärungen.

Mit Tags gruppieren

tagsParameter können zusammengehörige Routen gruppieren, um eine übersichtlichere Darstellung in der Dokumentation zu ermöglichen:

Beispiel

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=["User Management"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=["Product Management"])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

In der Swagger UI werden Routen nach Tag gruppiert angezeigt.

Dokumentation deaktivieren

In Produktionsumgebungen möchten Sie möglicherweise die automatische Dokumentation deaktivieren:

Beispiel

from fastapi import FastAPI

# Dokumentation deaktivieren
app = FastAPI(docs_url=None, redoc_url=None)

Zusammenfassung

  • FastAPI generiert automatisch zwei Arten interaktiver Dokumentation: Swagger UI und ReDoc
  • Der Dokumentationsinhalt wird automatisch anhand der Typannotationen im Code generiert, und die Dokumentation synchronisiert sich automatisch, wenn der Code aktualisiert wird
  • Nutzungtitle、description、tagsPassen Sie die Dokumentationsinformationen mit Parametern wie diesen an:
  • Funktions-Docstrings erscheinen ebenfalls in der Dokumentation.
  • Die Produktionsumgebung kann erreicht werden überdocs_url=NoneDokumentation deaktivieren
Weitere Erweiterungen