विषय पर बढ़ें

Request Example Data घोषित करें

🌐 एआई और मनुष्यों द्वारा किया गया अनुवाद

यह अनुवाद मनुष्यों के मार्गदर्शन में एआई द्वारा किया गया है। 🤝

इसमें मूल अर्थ को गलत समझने या अप्राकृतिक लगने आदि जैसी गलतियाँ हो सकती हैं। 🤖

आप हमें एआई LLM को बेहतर मार्गदर्शन करने में मदद करके इस अनुवाद को बेहतर बना सकते हैं।

अंग्रेज़ी संस्करण

आप उस data के examples घोषित कर सकते हैं जिसे आपका app receive कर सकता है।

इसे करने के कई तरीके यहाँ दिए गए हैं।

Pydantic models में अतिरिक्त JSON Schema data

आप किसी Pydantic model के लिए examples घोषित कर सकते हैं, जिन्हें generated JSON Schema में जोड़ा जाएगा।

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(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 def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

वह अतिरिक्त जानकारी उस model के output JSON Schema में जैसी है वैसी ही जोड़ी जाएगी, और API docs में उपयोग की जाएगी।

आप model_config attribute का उपयोग कर सकते हैं, जो एक dict लेता है, जैसा कि Pydantic के docs: Configuration में बताया गया है।

आप "json_schema_extra" को एक dict के साथ set कर सकते हैं जिसमें कोई भी अतिरिक्त data हो जिसे आप generated JSON Schema में दिखाना चाहते हैं, जिसमें examples भी शामिल हैं।

सुझाव

आप इसी technique का उपयोग JSON Schema को extend करने और अपनी custom अतिरिक्त जानकारी जोड़ने के लिए कर सकते हैं।

उदाहरण के लिए, आप इसका उपयोग frontend user interface आदि के लिए metadata जोड़ने में कर सकते हैं।

नोट

OpenAPI 3.1.0 (FastAPI 0.99.0 से उपयोग किया गया) ने examples के लिए support जोड़ा, जो JSON Schema standard का हिस्सा है।

उससे पहले, यह केवल keyword example को एक single example के साथ support करता था। यह अभी भी OpenAPI 3.1.0 द्वारा supported है, लेकिन deprecated है और JSON Schema standard का हिस्सा नहीं है। इसलिए आपको example से examples पर migrate करने के लिए प्रोत्साहित किया जाता है। 🤓

आप इस page के अंत में और पढ़ सकते हैं।

Field के अतिरिक्त arguments

Pydantic models के साथ Field() का उपयोग करते समय, आप अतिरिक्त examples भी घोषित कर सकते हैं:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(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 def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

JSON Schema - OpenAPI में examples

इनमें से किसी का भी उपयोग करते समय:

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

आप अतिरिक्त जानकारी के साथ examples का एक group भी घोषित कर सकते हैं, जिसे OpenAPI के अंदर उनके JSON Schemas में जोड़ा जाएगा।

examples के साथ Body

यहाँ हम Body() में अपेक्षित data के एक example वाला examples pass करते हैं:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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

docs UI में Example

ऊपर दिए गए किसी भी method के साथ यह /docs में इस तरह दिखेगा:

कई examples के साथ Body

बेशक आप कई examples भी pass कर सकते हैं:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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

जब आप ऐसा करते हैं, तो examples उस body data के internal JSON Schema का हिस्सा होंगे।

फिर भी, यह लिखते समय, Swagger UI, वह tool जो docs UI दिखाने के लिए जिम्मेदार है, JSON Schema में data के लिए कई examples दिखाने को support नहीं करता। लेकिन workaround के लिए नीचे पढ़ें।

OpenAPI-specific examples

JSON Schema द्वारा examples support किए जाने से पहले से ही, OpenAPI में एक अलग field के लिए support था जिसे examples भी कहा जाता था।

यह OpenAPI-specific examples OpenAPI specification में किसी अन्य section में जाता है। यह प्रत्येक JSON Schema के अंदर नहीं, बल्कि प्रत्येक path operation के details में जाता है।

और Swagger UI ने इस विशेष examples field को कुछ समय से support किया है। इसलिए, आप इसका उपयोग docs UI में अलग-अलग examples दिखाने के लिए कर सकते हैं।

इस OpenAPI-specific field examples का आकार एक dict है जिसमें कई examples होते हैं (list के बजाय), और प्रत्येक में अतिरिक्त जानकारी होती है जो OpenAPI में भी जोड़ी जाएगी।

यह OpenAPI में मौजूद प्रत्येक JSON Schema के अंदर नहीं जाता, यह बाहर, सीधे path operation में जाता है।

openapi_examples Parameter का उपयोग

आप FastAPI में OpenAPI-specific examples को parameter openapi_examples के साथ इनके लिए घोषित कर सकते हैं:

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

dict की keys प्रत्येक example की पहचान करती हैं, और प्रत्येक value एक और dict होती है।

examples में प्रत्येक specific example dict में ये हो सकते हैं:

  • summary: example के लिए छोटा description।
  • description: एक लंबा description जिसमें Markdown text हो सकता है।
  • value: यह दिखाया गया वास्तविक example है, जैसे एक dict।
  • externalValue: value का alternative, example की ओर point करने वाला URL। हालांकि यह शायद value जितने tools द्वारा supported न हो।

आप इसे इस तरह use कर सकते हैं:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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
🤓 Other versions and variants

Tip

Prefer to use the Annotated version if possible.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_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

Docs UI में OpenAPI Examples

Body() में openapi_examples जोड़ने के साथ /docs इस तरह दिखेगा:

तकनीकी विवरण

सुझाव

यदि आप पहले से ही FastAPI version 0.99.0 या उससे ऊपर का उपयोग कर रहे हैं, तो आप शायद ये details skip कर सकते हैं।

ये पुराने versions के लिए अधिक relevant हैं, OpenAPI 3.1.0 उपलब्ध होने से पहले।

आप इसे एक संक्षिप्त OpenAPI और JSON Schema history lesson मान सकते हैं। 🤓

चेतावनी

ये standards JSON Schema और OpenAPI के बारे में बहुत technical details हैं।

यदि ऊपर दिए गए ideas आपके लिए पहले से ही काम कर रहे हैं, तो वह पर्याप्त हो सकता है, और शायद आपको इन details की जरूरत नहीं है, इन्हें skip करने के लिए स्वतंत्र महसूस करें।

OpenAPI 3.1.0 से पहले, OpenAPI ने JSON Schema के एक पुराने और modified version का उपयोग किया।

JSON Schema में examples नहीं था, इसलिए OpenAPI ने अपने स्वयं के modified version में अपना example field जोड़ा।

OpenAPI ने specification के अन्य हिस्सों में भी example और examples fields जोड़े:

नोट

यह पुराना OpenAPI-specific examples parameter अब FastAPI 0.103.0 से openapi_examples है।

JSON Schema का examples field

लेकिन फिर JSON Schema ने specification के एक नए version में एक examples field जोड़ा।

और फिर नया OpenAPI 3.1.0 latest version (JSON Schema 2020-12) पर आधारित था, जिसमें यह नया field examples शामिल था।

और अब यह नया examples field पुराने single (और custom) example field पर precedence लेता है, जो अब deprecated है।

JSON Schema में यह नया examples field OpenAPI में अन्य जगहों (ऊपर वर्णित) की तरह अतिरिक्त metadata वाला dict नहीं है, यह सिर्फ एक list है।

नोट

OpenAPI 3.1.0 के JSON Schema के साथ इस नए सरल integration के साथ release होने के बाद भी, कुछ समय तक, Swagger UI, वह tool जो automatic docs प्रदान करता है, OpenAPI 3.1.0 को support नहीं करता था (यह version 5.0.0 से करता है 🎉)।

इसी वजह से, 0.99.0 से पहले के FastAPI versions अभी भी OpenAPI के 3.1.0 से कम versions का उपयोग करते थे।

Pydantic और FastAPI examples

जब आप Pydantic model के अंदर examples जोड़ते हैं, schema_extra या Field(examples=["something"]) का उपयोग करके, तो वह example उस Pydantic model के JSON Schema में जोड़ा जाता है।

और उस Pydantic model का JSON Schema आपकी API के OpenAPI में शामिल होता है, और फिर docs UI में उपयोग किया जाता है।

FastAPI के 0.99.0 से पहले के versions में (0.99.0 और ऊपर वाले नए OpenAPI 3.1.0 का उपयोग करते हैं), जब आप किसी भी अन्य utilities (Query(), Body(), आदि) के साथ example या examples का उपयोग करते थे, तो वे examples उस data का वर्णन करने वाले JSON Schema में नहीं जोड़े जाते थे (OpenAPI के JSON Schema के अपने version में भी नहीं), वे सीधे OpenAPI में path operation declaration में जोड़े जाते थे (OpenAPI के उन parts के बाहर जो JSON Schema का उपयोग करते हैं)।

लेकिन अब जबकि FastAPI 0.99.0 और ऊपर OpenAPI 3.1.0 का उपयोग करता है, जो JSON Schema 2020-12 का उपयोग करता है, और Swagger UI 5.0.0 और ऊपर, सब कुछ अधिक consistent है और examples JSON Schema में शामिल होते हैं।

Swagger UI और OpenAPI-specific examples

अब, क्योंकि Swagger UI कई JSON Schema examples को support नहीं करता था (2023-08-26 तक), users के पास docs में कई examples दिखाने का कोई तरीका नहीं था।

इसे solve करने के लिए, FastAPI 0.103.0 ने नए parameter openapi_examples के साथ उसी पुराने OpenAPI-specific examples field को घोषित करने के लिए support जोड़ा। 🤓

Summary

मैं कहा करता था कि मुझे history उतनी पसंद नहीं है... और अब मुझे देखिए, "tech history" lessons दे रहा हूँ। 😅

संक्षेप में, FastAPI 0.99.0 या उससे ऊपर upgrade करें, और चीजें बहुत अधिक सरल, consistent, और intuitive हैं, और आपको ये सारे historical details जानने की जरूरत नहीं है। 😎