Metadaten und URLs der Dokumentationen¶

Sie können mehrere Metadaten-Einstellungen für Ihre FastAPI-Anwendung konfigurieren.

Metadaten für die API¶

Sie können die folgenden Felder festlegen, welche in der OpenAPI-Spezifikation und den Benutzeroberflächen der automatischen API-Dokumentation verwendet werden:

Parameter Typ Beschreibung

title str Der Titel der API.

summary str Eine kurze Zusammenfassung der API. Verfügbar seit OpenAPI 3.1.0, FastAPI 0.99.0.

description str Eine kurze Beschreibung der API. Kann Markdown verwenden.

version string Die Version der API. Das ist die Version Ihrer eigenen Anwendung, nicht die von OpenAPI. Zum Beispiel 2.5.0.

terms_of_service str Eine URL zu den Nutzungsbedingungen für die API. Falls angegeben, muss es sich um eine URL handeln.

contact

dict

Die Kontaktinformationen für die verfügbar gemachte API. Kann mehrere Felder enthalten.

contact-Felder

Parameter	Typ	Beschreibung
`name`	`str`	Der identifizierende Name der Kontaktperson/Organisation.
`url`	`str`	Die URL, die auf die Kontaktinformationen verweist. MUSS im Format einer URL vorliegen.
`email`	`str`	Die E-Mail-Adresse der Kontaktperson/Organisation. MUSS im Format einer E-Mail-Adresse vorliegen.

license_info

dict

Die Lizenzinformationen für die verfügbar gemachte API. Kann mehrere Felder enthalten.

license_info-Felder

Parameter	Typ	Beschreibung
`name`	`str`	ERFORDERLICH (wenn eine `license_info` festgelegt ist). Der für die API verwendete Lizenzname.
`identifier`	`str`	Ein SPDX-Lizenzausdruck für die API. Das Feld `identifier` und das Feld `url` schließen sich gegenseitig aus. Verfügbar seit OpenAPI 3.1.0, FastAPI 0.99.0.
`url`	`str`	Eine URL zur Lizenz, die für die API verwendet wird. MUSS im Format einer URL vorliegen.

Sie können diese wie folgt setzen:

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

Tipp

Sie können Markdown in das Feld description schreiben und es wird in der Ausgabe gerendert.

Mit dieser Konfiguration würde die automatische API-Dokumentation wie folgt aussehen:

Lizenz-ID¶

Seit OpenAPI 3.1.0 und FastAPI 0.99.0 können Sie die license_info auch mit einem identifier anstelle einer url festlegen.

Zum Beispiel:

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "identifier": "MIT",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

Metadaten für Tags¶

Sie können mit dem Parameter openapi_tags auch zusätzliche Metadaten für die verschiedenen Tags hinzufügen, die zum Gruppieren Ihrer Pfadoperationen verwendet werden.

Es wird eine Liste benötigt, die für jedes Tag ein Dict enthält.

Jedes Dict kann Folgendes enthalten:

name (erforderlich): ein str mit demselben Tag-Namen, den Sie im Parameter tags in Ihren Pfadoperationen und APIRoutern verwenden.
description: ein str mit einer kurzen Beschreibung für das Tag. Sie kann Markdown enthalten und wird in der Benutzeroberfläche der Dokumentation angezeigt.
externalDocs: ein dict, das externe Dokumentation beschreibt mit:
- description: ein str mit einer kurzen Beschreibung für die externe Dokumentation.
- url (erforderlich): ein str mit der URL für die externe Dokumentation.

Metadaten für Tags erstellen¶

Versuchen wir das an einem Beispiel mit Tags für users und items.

Erstellen Sie Metadaten für Ihre Tags und übergeben Sie sie an den Parameter openapi_tags:

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Beachten Sie, dass Sie Markdown in den Beschreibungen verwenden können. Beispielsweise wird „login“ in Fettschrift (login) und „fancy“ in Kursivschrift (fancy) angezeigt.

Tipp

Sie müssen nicht für alle von Ihnen verwendeten Tags Metadaten hinzufügen.

Ihre Tags verwenden¶

Verwenden Sie den Parameter tags mit Ihren Pfadoperationen (und APIRoutern), um diese verschiedenen Tags zuzuweisen:

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Info

Lesen Sie mehr zu Tags unter Pfadoperation-Konfiguration.

Die Dokumentation anschauen¶

Wenn Sie nun die Dokumentation ansehen, werden dort alle zusätzlichen Metadaten angezeigt:

Reihenfolge der Tags¶

Die Reihenfolge der Tag-Metadaten-Dicts definiert auch die Reihenfolge, in der diese in der Benutzeroberfläche der Dokumentation angezeigt werden.

Auch wenn beispielsweise users im Alphabet nach items kommt, wird es vor diesen angezeigt, da wir seine Metadaten als erstes Dict der Liste hinzugefügt haben.

OpenAPI-URL¶

Standardmäßig wird das OpenAPI-Schema unter /openapi.json bereitgestellt.

Sie können das aber mit dem Parameter openapi_url konfigurieren.

Um beispielsweise festzulegen, dass es unter /api/v1/openapi.json bereitgestellt wird:

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

Wenn Sie das OpenAPI-Schema vollständig deaktivieren möchten, können Sie openapi_url=None festlegen, wodurch auch die Dokumentationsbenutzeroberflächen deaktiviert werden, die es verwenden.

URLs der Dokumentationen¶

Sie können die beiden enthaltenen Dokumentationsbenutzeroberflächen konfigurieren:

Swagger UI: bereitgestellt unter /docs.
- Sie können deren URL mit dem Parameter docs_url festlegen.
- Sie können sie deaktivieren, indem Sie docs_url=None festlegen.
ReDoc: bereitgestellt unter /redoc.
- Sie können deren URL mit dem Parameter redoc_url festlegen.
- Sie können sie deaktivieren, indem Sie redoc_url=None festlegen.

Um beispielsweise Swagger UI so einzustellen, dass sie unter /documentation bereitgestellt wird, und ReDoc zu deaktivieren:

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]