Wenn Sie Daten von einem <abbrtitle="Client: Eine Software, die sich mit einem Server verbindet.">Client</abbr> (sagen wir, einem Browser) zu Ihrer API senden, dann senden Sie diese als einen **Requestbody** (Deutsch: Anfragekörper).
Wenn Sie Daten von einem <abbrtitle="Client: Eine Software, die sich mit einem Server verbindet.">Client</abbr> (sagen wir, einem Browser) zu Ihrer API senden müssen, senden Sie sie als **Requestbody** (deutsch: Anfragekörper).
Ein **Request**body sind Daten, die vom Client zu Ihrer API gesendet werden. Ein **Response**body (Deutsch: Antwortkörper) sind Daten, die Ihre API zum Client sendet.
Ein **Request**body sind Daten, die vom Client zu Ihrer API gesendet werden. Ein **Response**body (deutsch: Antwortkörper) sind Daten, die Ihre API zum Client sendet.
Ihre API sendet fast immer einen **Response**body. Aber Clients senden nicht unbedingt immer **Request**bodys (sondern nur Metadaten).
Ihre API muss fast immer einen **Response**body senden. Aber Clients müssen nicht unbedingt immer **Requestbodys** senden, manchmal fordern sie nur einen Pfad an, vielleicht mit einigen Query-Parametern, aber senden keinen Body.
Um einen **Request**body zu deklarieren, verwenden Sie <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">Pydantic</a>-Modelle mit allen deren Fähigkeiten und Vorzügen.
Um einen **Request**body zu deklarieren, verwenden Sie <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">Pydantic</a>-Modelle mit all deren Fähigkeiten und Vorzügen.
/// info
/// info | Hinweis
Um Daten zu versenden, sollten Sie eines von: `POST` (meistverwendet), `PUT`, `DELETE` oder `PATCH` verwenden.
Um Daten zu senden, sollten Sie eines von: `POST` (meistverwendet), `PUT`, `DELETE` oder `PATCH` verwenden.
Senden Sie einen Body mit einem `GET`-Request, dann führt das laut Spezifikation zu undefiniertem Verhalten. Trotzdem wird es von FastAPI unterstützt, für sehr komplexe/extreme Anwendungsfälle.
Das Senden eines Bodys mit einem `GET`-Request hat ein undefiniertes Verhalten in den Spezifikationen, wird aber dennoch von FastAPI unterstützt, nur für sehr komplexe/extreme Anwendungsfälle.
Da aber davon abgeraten wird, zeigt die interaktive Dokumentation mit Swagger-Benutzeroberfläche die Dokumentation für den Body auch nicht an, wenn `GET` verwendet wird. Dazwischengeschaltete Proxys unterstützen es möglicherweise auch nicht.
Da davon abgeraten wird, zeigt die interaktive Dokumentation mit Swagger-Benutzeroberfläche die Dokumentation für den Body nicht an, wenn `GET` verwendet wird, und zwischengeschaltete Proxys unterstützen es möglicherweise nicht.
///
///
## Importieren Sie Pydantics `BaseModel`
## Importieren Sie Pydantics `BaseModel` { #import-pydantics-basemodel }
Zuerst müssen Sie `BaseModel` von `pydantic` importieren:
Zuerst müssen Sie `BaseModel` von `pydantic` importieren:
Wie auch bei Query-Parametern gilt, wenn ein Modellattribut einen Defaultwert hat, ist das Attribut nicht erforderlich. Ansonsten ist es erforderlich. Verwenden Sie `None`, um es als optional zu kennzeichnen.
Wie auch bei der Deklaration von Query-Parametern gilt: Wenn ein Modellattribut einen Defaultwert hat, ist das Attribut nicht erforderlich. Andernfalls ist es erforderlich. Verwenden Sie `None`, um es einfach optional zu machen.
Zum Beispiel deklariert das obige Modell ein JSON "`object`" (oder Python-`dict`) wie dieses:
Zum Beispiel deklariert das obige Modell ein JSON "`object`" (oder Python-`dict`) wie dieses:
@ -54,109 +54,112 @@ Da `description` und `tax` optional sind (mit `None` als Defaultwert), wäre fol
}
}
```
```
## Deklarieren Sie es als Parameter
## Deklarieren Sie es als Parameter { #declare-it-as-a-parameter }
Um es zu Ihrer *Pfadoperation* hinzuzufügen, deklarieren Sie es auf die gleiche Weise, wie Sie Pfad- und Query-Parameter deklariert haben:
Um es zu Ihrer *Pfadoperation* hinzuzufügen, deklarieren Sie es auf die gleiche Weise, wie Sie Pfad- und Query-Parameter deklariert haben:
... und deklarieren Sie seinen Typ als das Modell, welches Sie erstellt haben, `Item`.
... und deklarieren Sie dessen Typ als das Modell, welches Sie erstellt haben, `Item`.
## Resultate
## Resultate { #results }
Mit nur dieser Python-Typdeklaration, wird **FastAPI**:
Mit nur dieser Python-Typdeklaration wird **FastAPI**:
* Den Requestbody als JSON lesen.
* Den Requestbody als JSON lesen.
* Die entsprechenden Typen konvertieren (falls nötig).
* Die entsprechenden Typen konvertieren (falls nötig).
* Diese Daten validieren.
* Diese Daten validieren.
* Wenn die Daten ungültig sind, einen klar lesbaren Fehler zurückgeben, der anzeigt, wo und was die inkorrekten Daten waren.
* Wenn die Daten ungültig sind, wird ein klar lesbarer Fehler zurückgegeben, der genau anzeigt, wo und was die inkorrekten Daten sind.
* Ihnen die erhaltenen Daten im Parameter `item` übergeben.
* Ihnen die erhaltenen Daten im Parameter `item` übergeben.
* Da Sie diesen in der Funktion als vom Typ `Item` deklariert haben, erhalten Sie die ganze Editor-Unterstützung (Autovervollständigung, usw.) für alle Attribute und deren Typen.
* Da Sie ihn in der Funktion als vom Typ `Item` deklariert haben, erhalten Sie auch die volle Unterstützung des Editors (Autovervollständigung, usw.) für alle Attribute und deren Typen.
* Eine <ahref="https://json-schema.org"class="external-link"target="_blank">JSON Schema</a> Definition für Ihr Modell generieren, welche Sie überall sonst verwenden können, wenn es für Ihr Projekt Sinn macht.
* <ahref="https://json-schema.org"class="external-link"target="_blank">JSON Schema</a>-Definitionen für Ihr Modell generieren, die Sie auch überall sonst verwenden können, wenn es für Ihr Projekt Sinn macht.
* Diese Schemas werden Teil des generierten OpenAPI-Schemas und werden von den <abbrtitle="User Interface – Benutzeroberfläche">UIs</abbr> der automatischen Dokumentation verwendet.
* Diese Schemas werden Teil des generierten OpenAPI-Schemas und werden von den UIs der automatischen Dokumentation genutzt.
## Automatische Dokumentation
## Automatische Dokumentation { #automatic-docs }
Die JSON-Schemas Ihrer Modelle werden Teil ihrer OpenAPI-generierten Schemas und werden in der interaktiven API Dokumentation angezeigt:
Die JSON-Schemas Ihrer Modelle werden Teil Ihres OpenAPI-generierten Schemas und in der interaktiven API-Dokumentation angezeigt:
<imgsrc="/img/tutorial/body/image01.png">
<imgsrc="/img/tutorial/body/image01.png">
Und werden auch verwendet in der API-Dokumentation innerhalb jeder *Pfadoperation*, welche sie braucht:
Und werden auch in der API-Dokumentation innerhalb jeder *Pfadoperation*, die sie benötigt, verwendet:
<imgsrc="/img/tutorial/body/image02.png">
<imgsrc="/img/tutorial/body/image02.png">
## Editor Unterstützung
## Editor-Unterstützung { #editor-support }
In Ihrem Editor, innerhalb Ihrer Funktion, erhalten Sie Typhinweise und Code-Vervollständigung überall (was nicht der Fall wäre, wenn Sie ein `dict` anstelle eines PydanticModells erhalten hätten):
In Ihrem Editor erhalten Sie innerhalb Ihrer Funktion Typhinweise und Code-Vervollständigung überall (was nicht der Fall wäre, wenn Sie ein `dict` anstelle eines Pydantic-Modells erhalten hätten):
<imgsrc="/img/tutorial/body/image03.png">
<imgsrc="/img/tutorial/body/image03.png">
Sie bekommen auch Fehler-Meldungen für inkorrekte Typoperationen:
Sie bekommen auch Fehlermeldungen für inkorrekte Typoperationen:
<imgsrc="/img/tutorial/body/image04.png">
<imgsrc="/img/tutorial/body/image04.png">
Das ist nicht zufällig so, das ganze Framework wurde um dieses Design herum aufgebaut.
Das ist nicht zufällig so, das ganze Framework wurde um dieses Design herum aufgebaut.
Und es wurde in der Designphase gründlich getestet, vor der Implementierung, um sicherzustellen, dass es mit jedem Editor funktioniert.
Und es wurde in der Designphase gründlich getestet, bevor irgendeine Implementierung stattfand, um sicherzustellen, dass es mit allen Editoren funktioniert.
Es gab sogar ein paar Änderungen an Pydantic selbst, um das zu unterstützen.
Es gab sogar einige Änderungen an Pydantic selbst, um dies zu unterstützen.
Die vorherigen Screenshots zeigten<ahref="https://code.visualstudio.com"class="external-link"target="_blank">Visual Studio Code</a>.
Die vorherigen Screenshots wurden mit<ahref="https://code.visualstudio.com"class="external-link"target="_blank">Visual Studio Code</a> aufgenommen.
Aber Sie bekommen die gleiche Editor-Unterstützung in <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> und in den meisten anderen Python-Editoren:
Aber Sie würden die gleiche Editor-Unterstützung in <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> und den meisten anderen Python-Editoren erhalten:
<imgsrc="/img/tutorial/body/image05.png">
<imgsrc="/img/tutorial/body/image05.png">
/// tip | Tipp
/// tip | Tipp
Wenn Sie <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> als Ihren Editor verwenden, probieren Sie das <ahref="https://github.com/koxudaxi/pydantic-pycharm-plugin/"class="external-link"target="_blank">Pydantic PyCharm Plugin</a> aus.
Wenn Sie <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> als Ihren Editor verwenden, können Sie das <ahref="https://github.com/koxudaxi/pydantic-pycharm-plugin/"class="external-link"target="_blank">Pydantic PyCharm Plugin</a> ausprobieren.
Es verbessert die Editor-Unterstützung für Pydantic-Modelle, mit:
Es verbessert die Editor-Unterstützung für Pydantic-Modelle, mit:
* Code-Vervollständigung
* Code-Vervollständigung
* Typüberprüfungen
* Typüberprüfungen
* Refaktorisierung
* Refaktorisierung
* Suchen
* Suche
* Inspektionen
* Inspektionen
///
///
## Das Modell verwenden
## Das Modell verwenden { #use-the-model }
Innerhalb der Funktion können Sie alle Attribute des Modells direkt verwenden:
Innerhalb der Funktion können Sie alle Attribute des Modellobjekts direkt verwenden:
Sie können Pfad- und Requestbody-Parameter gleichzeitig deklarieren.
Sie können Pfad-Parameter und den Requestbody gleichzeitig deklarieren.
**FastAPI** erkennt, dass Funktionsparameter, die mit Pfad-Parametern übereinstimmen, **vom Pfad genommen** werden sollen, und dass Funktionsparameter, welche Pydantic-Modelle sind, **vom Requestbody genommen** werden sollen.
**FastAPI** erkennt, dass Funktionsparameter, die mit Pfad-Parametern übereinstimmen, **vom Pfad genommen** werden sollen, und dass Funktionsparameter, welche Pydantic-Modelle sind, **vom Requestbody genommen** werden sollen.
* Wenn der Parameter auch im **Pfad** deklariert wurde, wird er als Pfad-Parameter interpretiert.
* Wenn der Parameter auch im **Pfad** deklariert wurde, wird er als Pfad-Parameter verwendet.
* Wenn der Parameter ein **einfacher Typ** ist (wie `int`, `float`, `str`, `bool`, usw.), wird er als **Query**-Parameter interpretiert.
* Wenn der Parameter ein **einfacher Typ** ist (wie `int`, `float`, `str`, `bool`, usw.), wird er als **Query**-Parameter interpretiert.
* Wenn der Parameter vom Typ eines **Pydantic-Modells** ist, wird er als Request**body** interpretiert.
* Wenn der Parameter vom Typ eines **Pydantic-Modells** ist, wird er als Request**body** interpretiert.
/// note | Hinweis
/// note | Hinweis
FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, wegen des definierten Defaultwertes `= None`
FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, aufgrund des definierten Defaultwertes `= None`.
Das `str | None` (Python 3.10+) oder `Union` in `Union[str, None]` (Python 3.8+) wird von FastAPI nicht verwendet, um zu bestimmen, dass der Wert nicht erforderlich ist. FastAPI weiß, dass er nicht erforderlich ist, weil er einen Standardwert von `= None` hat.
Das `Union` in `Union[str, None]` wird von FastAPI nicht verwendet, aber es erlaubt Ihrem Editor, Sie besser zu unterstützen und Fehler zu erkennen.
Das Hinzufügen der Typannotationen ermöglicht jedoch Ihrem Editor, Ihnen eine bessere Unterstützung zu bieten und Fehler zu erkennen.
///
///
## Ohne Pydantic
## Ohne Pydantic { #without-pydantic }
Wenn Sie keine Pydantic-Modelle verwenden wollen, können Sie auch **Body**-Parameter nehmen. Siehe die Dokumentation unter [Body – Mehrere Parameter: Einfache Werte im Body](body-multiple-params.md#einzelne-werte-im-body){.internal-link target=\_blank}.
Wenn Sie keine Pydantic-Modelle verwenden möchten, können Sie auch **Body**-Parameter verwenden. Siehe die Dokumentation unter [Body – Mehrere Parameter: Einfache Werte im Body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
Nils Lindemann
2 weeks ago