Metadaten und Dokumentations-URLs¶

Sie können mehrere Metadaten-Konfigurationen in Ihrer FastAPI-Anwendung anpassen.

Metadaten für die API¶

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

Sie können diese wie folgt setzen:

fromfastapiimport 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 defread_items():
 return [{"name": "Katana"}]

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

Lizenzkennung¶

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:

fromfastapiimport 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": "Apache-2.0",
 },
)
@app.get("/items/")
async defread_items():
 return [{"name": "Katana"}]

Metadaten für Tags¶

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

Er nimmt eine Liste entgegen, die für jeden Tag ein Dictionary enthält.

Jedes Dictionary 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 es mit einem Beispiel mit Tags für users und items.

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

fromfastapiimport 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 defget_users():
 return [{"name": "Harry"}, {"name": "Ron"}]
@app.get("/items/", tags=["items"])
async defget_items():
 return [{"name": "wand"}, {"name": "flying broom"}]

Beachten Sie, dass Sie Markdown innerhalb der Beschreibungen verwenden können. Zum Beispiel wird „login" in Fettschrift (login) und „fancy" in Kursivschrift (fancy) angezeigt.

Ihre Tags verwenden¶

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

fromfastapiimport 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 defget_users():
 return [{"name": "Harry"}, {"name": "Ron"}]
@app.get("/items/", tags=["items"])
async defget_items():
 return [{"name": "wand"}, {"name": "flying broom"}]

Die Dokumentation testen¶

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

Reihenfolge der Tags¶

Die Reihenfolge der Tag-Metadaten-Dictionarys 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 deren Metadaten als erstes Dictionary 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:

fromfastapiimport FastAPI
app = FastAPI(openapi_url="/api/v1/openapi.json")
@app.get("/items/")
async defread_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.

Dokumentations-URLs¶

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:

fromfastapiimport FastAPI
app = FastAPI(docs_url="/documentation", redoc_url=None)
@app.get("/items/")
async defread_items():
 return [{"name": "Foo"}]