Beispiel-Request-Daten deklarieren¶

Sie können Beispiele für die Daten deklarieren, die Ihre App empfangen kann.

Hier sind mehrere Möglichkeiten, das zu tun.

Zusätzliche JSON-Schemadaten in Pydantic-Modellen¶

Sie können examples („Beispiele") für ein Pydantic-Modell deklarieren, welche dem generierten JSON-Schema hinzugefügt werden.

fromfastapiimport FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
 model_config = {
 "json_schema_extra": {
 "examples": [
 {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 }
 ]
 }
 }
@app.put("/items/{item_id}")
async defupdate_item(item_id: int, item: Item):
 results = {"item_id": item_id, "item": item}
 return results

Diese zusätzlichen Informationen werden unverändert zum für dieses Modell ausgegebenen JSON-Schema hinzugefügt und in der API-Dokumentation verwendet.

Sie können das Attribut model_config verwenden, das ein dict akzeptiert, wie beschrieben in Pydantic-Dokumentation: Configuration.

Sie können "json_schema_extra" setzen, mit einem dict, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich examples.

Zusätzliche Argumente für Field¶

Wenn Sie Field() mit Pydantic-Modellen verwenden, können Sie ebenfalls zusätzliche examples deklarieren:

fromfastapiimport FastAPI
frompydanticimport BaseModel, Field
app = FastAPI()
classItem(BaseModel):
 name: str = Field(examples=["Foo"])
 description: str | None = Field(default=None, examples=["A very nice Item"])
 price: float = Field(examples=[35.4])
 tax: float | None = Field(default=None, examples=[3.2])
@app.put("/items/{item_id}")
async defupdate_item(item_id: int, item: Item):
 results = {"item_id": item_id, "item": item}
 return results

examples im JSON-Schema – OpenAPI¶

Bei Verwendung von:

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

können Sie auch eine Gruppe von examples mit zusätzlichen Informationen deklarieren, die zu ihren JSON-Schemas innerhalb von OpenAPI hinzugefügt werden.

Body mit examples¶

Hier übergeben wir examples, welches ein einzelnes Beispiel für die in Body() erwarteten Daten enthält:

fromtypingimport Annotated
fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 item_id: int,
 item: Annotated[
 Item,
 Body(
 examples=[
 {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 }
 ],
 ),
 ],
):
 results = {"item_id": item_id, "item": item}
 return results

fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 item_id: int,
 item: Item = Body(
 examples=[
 {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 }
 ],
 ),
):
 results = {"item_id": item_id, "item": item}
 return results

Beispiel in der Dokumentations-Benutzeroberfläche¶

Mit jeder der oben genannten Methoden würde es in /docs so aussehen:

Body mit mehreren examples¶

Sie können natürlich auch mehrere examples übergeben:

fromtypingimport Annotated
fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 *,
 item_id: int,
 item: Annotated[
 Item,
 Body(
 examples=[
 {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 },
 {
 "name": "Bar",
 "price": "35.4",
 },
 {
 "name": "Baz",
 "price": "thirty five point four",
 },
 ],
 ),
 ],
):
 results = {"item_id": item_id, "item": item}
 return results

fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 *,
 item_id: int,
 item: Item = Body(
 examples=[
 {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 },
 {
 "name": "Bar",
 "price": "35.4",
 },
 {
 "name": "Baz",
 "price": "thirty five point four",
 },
 ],
 ),
):
 results = {"item_id": item_id, "item": item}
 return results

Wenn Sie das tun, werden die Beispiele Teil des internen JSON-Schemas für diese Body-Daten.

Nichtsdestotrotz unterstützt Swagger UI, das für die Anzeige der Dokumentations-Benutzeroberfläche zuständige Tool, zum Zeitpunkt der Erstellung nicht die Anzeige mehrerer Beispiele für die Daten in JSON Schema. Aber lesen Sie unten für einen Workaround weiter.

OpenAPI-spezifische examples¶

Schon bevor JSON Schema examples unterstützte, unterstützte OpenAPI ein anderes Feld, das auch examples genannt wurde.

Diese OpenAPI-spezifischen examples finden sich in einem anderen Abschnitt der OpenAPI-Spezifikation. Sie sind Details für jede Pfadoperation, nicht für jedes JSON-Schema.

Und Swagger UI unterstützt dieses spezielle Feld examples schon seit einiger Zeit. Sie können es also verwenden, um verschiedene Beispiele in der Benutzeroberfläche der Dokumentation anzuzeigen.

Das Format dieses OpenAPI-spezifischen Felds examples ist ein dict mit mehreren Beispielen (anstelle einer list), jedes mit zusätzlichen Informationen, die auch zu OpenAPI hinzugefügt werden.

Dies erfolgt nicht innerhalb jedes in OpenAPI enthaltenen JSON-Schemas, sondern außerhalb, in der Pfadoperation.

Den Parameter openapi_examples verwenden¶

Sie können die OpenAPI-spezifischen examples in FastAPI mit dem Parameter openapi_examples deklarieren, für:

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

Die Schlüssel des dict identifizieren jedes Beispiel, und jeder Wert ist ein weiteres dict.

Jedes spezifische Beispiel-dict in den examples kann Folgendes enthalten:

• summary: Kurze Beschreibung für das Beispiel.
• description: Eine lange Beschreibung, die Markdown-Text enthalten kann.
• value: Dies ist das tatsächlich angezeigte Beispiel, z. B. ein dict.
• externalValue: Alternative zu value, eine URL, die auf das Beispiel verweist. Allerdings wird dies möglicherweise nicht von so vielen Tools unterstützt wie value.

Sie können es so verwenden:

fromtypingimport Annotated
fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 *,
 item_id: int,
 item: Annotated[
 Item,
 Body(
 openapi_examples={
 "normal": {
 "summary": "A normal example",
 "description": "A **normal** item works correctly.",
 "value": {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 },
 },
 "converted": {
 "summary": "An example with converted data",
 "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
 "value": {
 "name": "Bar",
 "price": "35.4",
 },
 },
 "invalid": {
 "summary": "Invalid data is rejected with an error",
 "value": {
 "name": "Baz",
 "price": "thirty five point four",
 },
 },
 },
 ),
 ],
):
 results = {"item_id": item_id, "item": item}
 return results

fromfastapiimport Body, FastAPI
frompydanticimport BaseModel
app = FastAPI()
classItem(BaseModel):
 name: str
 description: str | None = None
 price: float
 tax: float | None = None
@app.put("/items/{item_id}")
async defupdate_item(
 *,
 item_id: int,
 item: Item = Body(
 openapi_examples={
 "normal": {
 "summary": "A normal example",
 "description": "A **normal** item works correctly.",
 "value": {
 "name": "Foo",
 "description": "A very nice Item",
 "price": 35.4,
 "tax": 3.2,
 },
 },
 "converted": {
 "summary": "An example with converted data",
 "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
 "value": {
 "name": "Bar",
 "price": "35.4",
 },
 },
 "invalid": {
 "summary": "Invalid data is rejected with an error",
 "value": {
 "name": "Baz",
 "price": "thirty five point four",
 },
 },
 },
 ),
):
 results = {"item_id": item_id, "item": item}
 return results

OpenAPI-Beispiele in der Dokumentations-Benutzeroberfläche¶

Wenn openapi_examples zu Body() hinzugefügt wird, würde /docs so aussehen:

Technische Details¶

Vor OpenAPI 3.1.0 verwendete OpenAPI eine ältere und modifizierte Version von JSON Schema.

JSON Schema hatte keine examples, daher fügte OpenAPI seiner eigenen modifizierten Version ein eigenes example-Feld hinzu.

OpenAPI fügte auch die Felder example und examples zu anderen Teilen der Spezifikation hinzu:

• Parameter Object (in der Spezifikation), das verwendet wurde von FastAPIs:
  • Path()
  • Query()
  • Header()
  • Cookie()
• Request Body Object im Feld content des Media Type Objects (in der Spezifikation), das verwendet wurde von FastAPIs:
  • Body()
  • File()
  • Form()

JSON Schemas Feld examples¶

Aber dann fügte JSON Schema ein examples-Feld zu einer neuen Version der Spezifikation hinzu.

Und dann basierte das neue OpenAPI 3.1.0 auf der neuesten Version (JSON Schema 2020-12), die dieses neue Feld examples enthielt.

Und jetzt hat dieses neue examples-Feld Vorrang vor dem alten (und benutzerdefinierten) example-Feld, im Singular, das jetzt deprecatet ist.

Dieses neue examples-Feld in JSON Schema ist nur eine list von Beispielen, kein Dict mit zusätzlichen Metadaten wie an den anderen Stellen in OpenAPI (oben beschrieben).

Pydantic- und FastAPI-examples¶

Wenn Sie examples innerhalb eines Pydantic-Modells hinzufügen, indem Sie schema_extra oder Field(examples=["something"]) verwenden, wird dieses Beispiel dem JSON-Schema für dieses Pydantic-Modell hinzugefügt.

Und dieses JSON-Schema des Pydantic-Modells ist in der OpenAPI Ihrer API enthalten und wird dann in der Benutzeroberfläche der Dokumentation verwendet.

In Versionen von FastAPI vor 0.99.0 (0.99.0 und höher verwenden das neuere OpenAPI 3.1.0), wenn Sie example oder examples mit einem der anderen Werkzeuge (Query(), Body(), usw.) verwendet haben, wurden diese Beispiele nicht zum JSON-Schema hinzugefügt, das diese Daten beschreibt (nicht einmal zur OpenAPI-eigenen Version von JSON Schema), sondern direkt zur Pfadoperation-Deklaration in OpenAPI (außerhalb der Teile von OpenAPI, die JSON Schema verwenden).

Aber jetzt, da FastAPI 0.99.0 und höher, OpenAPI 3.1.0 verwendet, das JSON Schema 2020-12 verwendet, und Swagger UI 5.0.0 und höher, ist alles konsistenter und die Beispiele sind in JSON Schema enthalten.

Swagger UI und OpenAPI-spezifische examples¶

Da Swagger UI derzeit nicht mehrere JSON Schema Beispiele unterstützt (Stand: 26.08.2023), hatten Benutzer keine Möglichkeit, mehrere Beispiele in der Dokumentation anzuzeigen.

Um dieses Problem zu lösen, hat FastAPI 0.103.0 Unterstützung für die Deklaration desselben alten OpenAPI-spezifischen examples-Felds mit dem neuen Parameter openapi_examples hinzugefügt. 🤓

Zusammenfassung¶

Ich habe immer gesagt, dass ich Geschichte nicht so sehr mag ... und jetzt schauen Sie mich an, wie ich „Technikgeschichte"-Unterricht gebe. 😅

Kurz gesagt: Aktualisieren Sie auf FastAPI 0.99.0 oder höher, und die Dinge sind viel einfacher, konsistenter und intuitiver, und Sie müssen nicht alle diese historischen Details kennen. 😎