FastAPI otomatik belgelendirmeyi nasıl oluşturuyor?

Question

Accepted Answer

FastAPI **kodunuzdan otomatik olarak etkileşimli API belgelendirmesi oluşturur** — rotalarınız, parametreleriniz ve Pydantic modelleriniz bir OpenAPI şemasına dönüştürülür, bu da iki tarayıcıda görüntülenebilir belgelendirme arayüzünü (Swagger UI ve ReDoc) hiçbir ek çaba olmadan güçlendirir.

## Belgeleri ücretsiz alıyorsunuz

```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
```

Yazdığınız türü belirtilen bitiş noktaları ve modellerle FastAPI tam belgelendirme üretir — ayrı bir belgelendirme dosyası yazmanız veya korumanız gerekmez.

## İki yerleşik belgelendirme arayüzü

```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` adresini ziyaret edin ve her bitiş noktayı keşfedebilir, gerekli parametreleri ve yanıt şekillerini görebilir, ve **gerçek istekleri** doğrudan tarayıcıdan gönderebilirsiniz — geliştirme sırasında ve API tüketicileri için vazgeçilmezdir.

## Belgelendirme içeriği nereden geliyor

```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
```

Her şey zaten yazdığınız koddan türetilmiştir — belgeler otomatik olarak **uyumlu kalır** uygulamayla.

## Belgeleri zenginleştirmek

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

## Neden önemli

Otomatik etkileşimli belgelendirme, FastAPI'nin en ünlü özelliklerinden biri ve popülaritesinin ana nedenidir.

Belgeler kodunuzdan doğrudan oluşturulduğu için (rotalar, tür ipuçları, Pydantic modelleri, docstring'ler), bunlar her zaman **uyumludur** gerçek uygulamayla — el yazısı belgeleri dehşete düşüren belgelendirmenin güncelliğini yitirmesi sorununun ortadan kaldırılması.

Etkileşimli Swagger UI (`/docs`) geliştiricilere ve API tüketicilerine bitiş noktaları **tarayıcıda canlı olarak test etme** olanağı sunar, geliştirici deneyimini önemli ölçüde iyileştirir ve entegrasyon sürtünmesini azaltır.

Oluşturulan OpenAPI şeması, istemci SDK oluşturma ve sözleşme testini de yönlendirebilir.

Profesyonel, doğru, etkileşimli API belgelerini temelde ücretsiz almak — sadece iyi türü belirtilmiş kod yazarak — önemli bir verimlilik ve kalite kazancı, bu da FastAPI'nin önemli ve ayırt edici bir yeteneğini oluşturur.