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:
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 freigegebene API. Kann mehrere Felder enthalten.
|
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
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 im Feld description
verwenden, und es wird in der Ausgabe gerendert.
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:
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 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): einstr
mit demselben Tag-Namen, den Sie im Parametertags
in Ihren Pfadoperationen undAPIRouter
n verwenden.description
: einstr
mit einer kurzen Beschreibung für das Tag. Sie kann Markdown enthalten und wird in der Benutzeroberfläche der Dokumentation angezeigt.externalDocs
: eindict
, das externe Dokumentation beschreibt mit:description
: einstr
mit einer kurzen Beschreibung für die externe Dokumentation.url
(erforderlich): einstr
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
:
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 innerhalb der Beschreibungen verwenden können. Zum Beispiel 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 APIRouter
n), 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 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:
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.
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.
- Sie können deren URL mit dem Parameter
- 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.
- Sie können deren URL mit dem Parameter
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"}]