FastAPI Dokümantasyonunda Gezinme: Yeni Başlayandan Uzmaya

Resmi FastAPI dokümantasyonu (fastapi.tiangolo.com) iki ana bölümden oluşur: Tutorial (örneklerle adım adım eğitim) ve Reference (API referansı). Hızlıca cevap bulmak için kavramları anlamak ve tipik görevleri çözmek amacıyla Tutorial'ı, fonksiyon imzalarını ve parametreleri netleştirmek için ise Reference'ı kullanın. Çalışan belirli bir uygulamayı analiz etmek için her zaman yerleşik /docs (Swagger UI) ve /redoc arayüzlerine başvurun.

Aşağıda, saatlerce okumaktan kurtaracak etkili bilgi arama stratejisi sunulmaktadır.

Resmi dokümantasyonun yapısı

Sitenin mimarisini anlamak, menülerde kaybolmadan doğrudan ilgili bölüme gitmenizi sağlar.

1. Tutorial (Eğitim Rehberi)

Geliştiricilerin %90'u için ana kaynak budur. Mantıksal bloklara ayrılmıştır:

• User Guide: Temeller (yol parametreleri, sorgular, istek gövdeleri).
• Advanced User Guide: İleri düzey konular (bağımlılıklar, güvenlik, middleware, WebSocket).
• Features: Framework'ün yeteneklerinin açıklaması.

Sol taraftaki kenar çubuğunu içerik tablosu olarak kullanın. Bir konuyu ilk kez inceliyorsanız sırayla okuyun. Belirli bir görev için çözüm arıyorsanız (örneğin, "dosya yükleme"), sayfa içinde arama (Ctrl+F) veya sitede genel arama kullanın.

2. Reference (API Referansı)

Burada FastAPI ve Starlette sınıfları, fonksiyonları ve modülleri hakkında teknik bilgiler bulunur.

• Ne zaman açılır: Hangi fonksiyonu kullanacağınızı bildiğinizde (örneğin, Depends veya Query), ancak tam parametre adını veya olası değerleri unuttuğunuzda.
• Özelliği: Metin kuru olup, "neden" sorusuna dair gereksiz açıklamalar içermez. Sadece imzalar ve veri tipleri bulunur.

3. Local Docs (Yerleşik Dokümantasyon)

FastAPI, OpenAPI standardına dayalı interaktif dokümantasyon oluşturur.

• Swagger UI (/docs): Endpoint'leri doğrudan tarayıcıdan test etmenize olanak tanır ("Try it out").
• ReDoc (/redoc): Spesifikasyonları okumak için daha uygun, daha katı ve temiz bir dokümantasyon görünümü sunar.

İstenen bilgilere hızlıca nasıl ulaşılır

Cevabı arama yöntemi, sorunuzun türüne bağlıdır. İşte kanıtlanmış senaryolar:

Senaryo 1: "X işlevselliğini nasıl implemente ederim?"

Hemen Google'da aramayın. Tutorial'ı açın ve anahtar kelimelerle arama yapın.

• Örnek: Erişim hakları kontrolü eklemek gerekiyor.
• Eylem: Tutorial menüsünde "Security" veya "Dependencies" bölümünü arayın. Kod örneklerini okuyun.

Senaryo 2: "Bu hata ne anlama geliyor / hangi parametreyi geçmeliyim?"

Kod çalışmıyorsa veya IDE bir hatayı vurguluyorsa, Reference'a başvurun.

• Örnek: Path(...) ile Query(...) arasındaki fark net değil.
• Eylem: Reference'da ilgili fonksiyonları bulun ve default, alias, title argümanlarının açıklamasına bakın.

Senaryo 3: "Mevcut API'm nasıl yapılandırılmış?"

Yerel Swagger'ı kullanın.

• Eylem: Uygulamayı başlatın (uvicorn main:app --reload) ve http://127.0.0.1:8000/docs adresini açın.
• Burada tüm mevcut rotaları, gerekli parametreleri ve yanıt modellerini göreceksiniz. Bu, başkasının veya kendi eski projenizin yapısını anlamanın en hızlı yoludur.

OpenAPI ile çalışma ve otomatik dokümantasyon

Geliştiriciler sık sık, büyük bir projede istenen bölümü "bulmanın" en iyi yolunun onu doğru şekilde yapılandırmak olduğunu unuturlar. FastAPI, dokümantasyonun Swagger'da nasıl görüntülendiğini yönetmenize olanak tanır.

Tag'ler aracılığıyla endpoint gruplama

Çok sayıda rotanız varsa, /docs listesi kaosa dönüşür. Router'larda tags parametresini kullanın.

from fastapi import APIRouter

# "users" tag'i ile bir router oluşturun
user_router = APIRouter(
    prefix="/users",
    tags=["users"],  # Buradaki tüm endpoint'ler "users" grubunda olacak
    responses={404: {"description": "Not found"}},
)

@user_router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

Bu yaklaşım, Swagger UI'da net bölümler oluşturarak gereksiz grupları hızlıca daraltmanıza ve belirli bir modüle odaklanmanıza olanak tanır.

Meta veriler ve açıklamalar

Her endpoint'e summary ve description ekleyin. Bu, /docs içindeki aramayı anlamlı hale getirir.

@app.post("/items/", summary="Yeni ürün oluştur", description="Ürün verilerini içeren JSON kabul eder ve oluşturulan nesneyi döndürür")
async def create_item(item: Item):
    ...

Bilgi kaynaklarının karşılaştırılması

Dokümantasyonla çalışırken yapılan yaygın hatalar

1. Reference'ı baştan sona okumak. Bu bir referanstır, ders kitabı değildir. Ezberlemeye çalışmak zaman kaybına neden olur. Sadece sözlük olarak kullanın.
2. "Dependencies" bölümünü görmezden gelmek. Birçok yeni başlayan, her endpoint'te manuel yetkilendirme mantığı yazmaya çalışır, oysa Tutorial'da bu görevleri zarifçe çözen güçlü bir Depends bölümü vardır.
3. Gereksiz yere production ortamında dokümantasyonu devre dışı bırakmak. Güvenlik dikkatli olmayı gerektirse de, hızlı hata ayıklama için iç ağlarda /docs erişimine sahip olmak genellikle faydalıdır. Devre dışı bırakıyorsanız, bunu FastAPI() nesnesinde docs_url=None parametresiyle yapın.

SSS

S: Veritabanı entegrasyonu (SQLAlchemy, Tortoise) hakkında bilgiyi nerede bulabilirim? C: Tutorial -> "SQL Databases" bölümünde. FastAPI belirli bir ORM'ye bağlı değildir, bu nedenle SQLAlchemy için genel prensipler ve örnekler verilmiştir.

S: Otomatik dokümantasyonu nasıl devre dışı bırakırım? C: Uygulamayı oluştururken docs_url=None ve redoc_url=None parametrelerini geçin: app = FastAPI(docs_url=None, redoc_url=None)

S: Kod değiştikten sonra dokümantasyon güncellenmiyor. C: Sunucuyu yeniden başlattığınızdan emin olun. uvicorn kullanıyorsanız, dosyalardaki değişikliklerde otomatik yeniden yükleme için --reload flag'ini ekleyin.

S: Dokümantasyonu PDF olarak nasıl dışa aktarırım? C: Resmi olarak böyle bir özellik yoktur. Swagger'a kıyasla baskı için daha iyi biçimlendirildiğinden, /redoc sayfasında tarayıcıdan sayfayı yazdırma (Ctrl+P -> PDF olarak kaydet) yöntemini kullanabilirsiniz.