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:
fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou 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/")asyncdefread_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:
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:
fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou 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/")asyncdefread_items():return[{"name":"Katana"}]
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.
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:
fromfastapiimportFastAPItags_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"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_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.
Verwenden Sie den Parameter tags mit Ihren Pfadoperationen (und APIRoutern), um diese verschiedenen Tags zuzuweisen:
fromfastapiimportFastAPItags_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"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]
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.
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.