كيف يقوم FastAPI بإنشاء التوثيق التلقائي؟

Question

Accepted Answer

يقوم FastAPI **بإنشاء توثيق API تفاعلي تلقائياً** من الكود الخاص بك — تُحول مساراتك وبارامتراتك وموديلات Pydantic إلى مخطط OpenAPI، والذي يعمل على واجهي مستخدم قابلتي للاستعراض (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
```

بمجرد كتابة endpoints وموديلات مكتوبة، ينتج FastAPI توثيقاً كاملاً — بدون ملف توثيق منفصل لكتابته أو صيانته.

## واجهات المستخدم المدمجة الاثنتان

```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، ورؤية البارامترات المطلوبة وأشكال الاستجابة، و**أرسل طلبات حقيقية** مباشرة من المتصفح — لا غنى عنها أثناء التطوير ولمستخدمي API.

## من أين يأتي محتوى التوثيق

```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 احتفاءً به وأحد الأسباب الرئيسية لشهرتها.

لأن التوثيق يُنشأ مباشرة من الكود الخاص بك (المسارات، تلميحات النوع، موديلات Pydantic، docstrings)، فهو دائماً **متزامن** مع التنفيذ الفعلي — مما يلغي مشكلة التوثيق الذي ينحرف عن التاريخ، والتي تصيب التوثيق المكتوب يدويًا.

تتيح واجهة Swagger UI التفاعلية (`/docs`) للمطورين ومستهلكي API استكشاف و**اختبار endpoints مباشرة في المتصفح**، مما يحسن بشكل كبير تجربة المطور وتقلل احتكاك التكامل.

يمكن أيضاً لمخطط OpenAPI المُنشأ أن يعمل على توليد عميل SDK واختبار العقد.

الحصول على توثيق API احترافي وقطقيق وتفاعلي بشكل أساسي مجاناً — بمجرد كتابة كود مكتوب جيداً — هو فوز كبير في الإنتاجية والجودة، مما يجعل هذه قدرة FastAPI مهمة ومميزة.