FastAPI خودکار دستاویزات کیسے تیار کرتا ہے؟

Question

Accepted Answer

FastAPI **آپ کے کوڈ سے خودکار طور پر انٹرایکٹو API دستاویزات تیار کرتا ہے** — آپ کے routes، parameters، اور Pydantic ماڈلز کو OpenAPI schema میں تبدیل کیا جاتا ہے، جو دو قابل برائوز doc UIs (Swagger UI اور ReDoc) کو بغیر کسی اضافی کوشش کے فراہم کرتا ہے۔

## آپ کو مفت میں دستاویزات ملتی ہیں

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

صرف typed endpoints اور ماڈلز لکھ کر، FastAPI مکمل دستاویزات تیار کرتا ہے — کوئی الگ documentation فائل لکھنی یا برقرار رکھنی نہیں۔

## دونوں built-in doc UIs

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

`/docs` پر جائیں اور آپ ہر endpoint کو دیکھ سکتے ہیں، required parameters اور response shapes دیکھ سکتے ہیں، اور **براہ راست براؤزر سے حقیقی requests بھیج سکتے ہیں** — تطویر اور API صارفین کے لیے انمول۔

## doc کا مواد کہاں سے آتا ہے

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

سب کچھ آپ جو کوڈ پہلے سے لکھتے ہیں اس سے اخذ کیا جاتا ہے — دستاویزات خودکار طور پر **نفاذ کے ساتھ مطابقت رکھتی ہیں**۔

## دستاویزات کو بہتر بنانا

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## یہ کیوں اہم ہے

خودکار انٹرایکٹو دستاویزات FastAPI کی سب سے زیادہ منظوری والی خصوصیات میں سے ایک ہے اور اس کی مقبولیت کی بڑی وجہ ہے۔

چونکہ دستاویزات براہ راست آپ کے کوڈ (routes، type hints، Pydantic ماڈلز، docstrings) سے تیار ہوتی ہیں، وہ ہمیشہ **اصل نفاذ کے ساتھ مطابقت رکھتی ہیں** — دستاویزات کے پرانے ہونے کے دائمی مسئلے کو ختم کرتے ہوئے، جو ہاتھ سے لکھی گئی دستاویزات کو پریشان کرتا ہے۔

انٹرایکٹو Swagger UI (`/docs`) ڈیولپرز اور API صارفین کو براؤزر میں endpoints کو **براہ راست ٹیسٹ کرنے** کی اجازت دیتا ہے، جو ڈیولپر کے تجربے کو نمایاں طور پر بہتر بناتا ہے اور انضمام کی رکاوٹوں کو کم کرتا ہے۔

تیار شدہ OpenAPI schema client SDK generation اور contract testing کو بھی چلا سکتا ہے۔

صرف اچھی طریقے سے typed کوڈ لکھ کر — بغیر کسی خاص کوشش کے — پروفیشنل، درست، انٹرایکٹو API دستاویزات حاصل کرنا ایک اہم پیداواری اور معیار کی فتح ہے، یہ FastAPI کی ایک اہم، منفرد صلاحیت بناتا ہے۔