OpenAPI erweitern¶
In einigen Fällen müssen Sie möglicherweise das generierte OpenAPI-Schema ändern.
In diesem Abschnitt erfahren Sie, wie.
Der normale Vorgang¶
Der normale (Standard-)Prozess ist wie folgt.
Eine FastAPI-Anwendung (-Instanz) verfügt über eine .openapi()-Methode, von der erwartet wird, dass sie das OpenAPI-Schema zurückgibt.
Als Teil der Erstellung des Anwendungsobjekts wird eine Pfadoperation für /openapi.json (oder welcher Wert für den Parameter openapi_url gesetzt wurde) registriert.
Diese gibt lediglich eine JSON-Response zurück, mit dem Ergebnis der Methode .openapi() der Anwendung.
Standardmäßig überprüft die Methode .openapi() die Eigenschaft .openapi_schema, um zu sehen, ob diese Inhalt hat, und gibt diesen zurück.
Ist das nicht der Fall, wird der Inhalt mithilfe der Hilfsfunktion unter fastapi.openapi.utils.get_openapi generiert.
Und diese Funktion get_openapi() erhält als Parameter:
title: Der OpenAPI-Titel, der in der Dokumentation angezeigt wird.version: Die Version Ihrer API, z. B.2.5.0.openapi_version: Die Version der verwendeten OpenAPI-Spezifikation. Standardmäßig die neueste Version:3.1.0.summary: Eine kurze Zusammenfassung der API.description: Die Beschreibung Ihrer API. Dies kann Markdown enthalten und wird in der Dokumentation angezeigt.routes: Eine Liste von Routen, dies sind alle registrierten Pfadoperationen. Sie stammen vonapp.routes.
Info
Der Parameter summary ist in OpenAPI 3.1.0 und höher verfügbar und wird von FastAPI 0.99.0 und höher unterstützt.
Überschreiben der Standardeinstellungen¶
Mithilfe der oben genannten Informationen können Sie dieselbe Hilfsfunktion verwenden, um das OpenAPI-Schema zu generieren und jeden benötigten Teil zu überschreiben.
Fügen wir beispielsweise ReDocs OpenAPI-Erweiterung zum Einbinden eines benutzerdefinierten Logos hinzu.
Normales FastAPI¶
Schreiben Sie zunächst wie gewohnt Ihre ganze FastAPI-Anwendung:
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Das OpenAPI-Schema generieren¶
Verwenden Sie dann dieselbe Hilfsfunktion, um das OpenAPI-Schema innerhalb einer custom_openapi()-Funktion zu generieren:
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Das OpenAPI-Schema ändern¶
Jetzt können Sie die ReDoc-Erweiterung hinzufügen und dem info-„Objekt“ im OpenAPI-Schema ein benutzerdefiniertes x-logo hinzufügen:
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Zwischenspeichern des OpenAPI-Schemas¶
Sie können die Eigenschaft .openapi_schema als „Cache“ verwenden, um Ihr generiertes Schema zu speichern.
Auf diese Weise muss Ihre Anwendung das Schema nicht jedes Mal generieren, wenn ein Benutzer Ihre API-Dokumentation öffnet.
Es wird nur einmal generiert und dann wird dasselbe zwischengespeicherte Schema für die nächsten Requests verwendet.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Die Methode überschreiben¶
Jetzt können Sie die Methode .openapi() durch Ihre neue Funktion ersetzen.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Testen¶
Sobald Sie auf http://127.0.0.1:8000/redoc gehen, werden Sie sehen, dass Ihr benutzerdefiniertes Logo verwendet wird (in diesem Beispiel das Logo von FastAPI):
