Mevcut İsteklerden OpenAPI Spesifikasyonları Nasıl Oluşturulur

Sıfırdan bir OpenAPI belirtimi yazmak, özellikle API'niz zaten canlı ve çalışır durumdayken çok zaman alabilir. Birçok ekip, çok az veya hiç belgelendirilmemiş projeleri devralır ya da erken geliştirme aşamasında hızla oluşturulmuş API'lerle çalışır. Bu durumlarda, belge oluşturmanın en pratik yolu, mevcut API isteklerinizden doğrudan bir OpenAPI belirtimi oluşturmaktır.

Bu kılavuz, bu yaklaşımın neden işe yaradığını, hangi araçların yardımcı olabileceğini ve gerçek istekleri ekibinizin güvenebileceği temiz, yeniden kullanılabilir bir OpenAPI belirtimine nasıl dönüştürebileceğinizi açıklamaktadır.

Yöntem 1: "Kod Odaklı" Yaklaşım

Bu yöntem, arka uç uygulama kodunuza doğrudan açıklamalar veya kütüphaneler ekleyebiliyorsanız işe yarar.

Nasıl Çalışır?

Web çatınızda (framework) kodunuzu (rotalarınızı, kontrolcülerinizi ve modellerinizi) inceleyen ve anında bir OpenAPI belirtimi oluşturan bir kütüphane kurarsınız.

Popüler Kütüphaneler:

• Node.js (Express): swagger-jsdoc veya tsoa (TypeScript OpenAPI)
• Python (FastAPI/Flask): FastAPI'de bu yerleşik olarak bulunur! Flask, flasgger veya flask-restx kullanabilir.
• Java (Spring Boot): springdoc-openapi
• .NET: Swashbuckle

FastAPI (Python) ile Örnek:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the database.
    - **name**: The item's name
    - **price**: The item's price in USD
    """
    return item

# Bu kod, /docs veya /openapi.json adresinde tam bir OpenAPI belirtimini otomatik olarak oluşturur

Artıları:

• Her zaman doğru: Belirtim, doğrudan çalışan koddan türetilir.
• Düşük bakım gereksinimi: Kodu güncellediğinizde, belirtim otomatik olarak güncellenir.

Eksileri:

• Koda erişim gerektirir: Bu yöntemi kontrol etmediğiniz üçüncü taraf veya eski API'ler için kullanamazsınız.
• Kodu karmaşıklaştırabilir: Kapsamlı OpenAPI açıklamaları, iş mantığını okumayı zorlaştırabilir.

Yöntem 2: "Trafik Analizi" Yaklaşımı

Bu, akıllıca bir "dıştan içe" yaklaşımdır. İstemciler ve API'niz arasındaki gerçek HTTP trafiğini yakalarsınız ve ardından belirtimi çıkarmak için analiz edersiniz.

Nasıl Çalışır?

Bir proxy veya ağ sniffer'ı olarak işlev gören bir araç kullanırsınız. Tüm API trafiği bu araç üzerinden yönlendirilir. Araç, istek ve yanıtları (URL'ler, yöntemler, başlıklar, gövdeler) analiz eder ve API'nizin bir modelini oluşturur.

Popüler Araçlar:

• Akita Software: API trafiğini otomatik olarak gözlemleyerek belirtimler oluşturur ve izler.
• HAR dosyası oluşturma: Tarayıcınızın Geliştirici Araçları'nı (Ağ sekmesi) kullanarak API'nizle bir oturumu kaydedebilir ve bir HAR (HTTP Arşivi) dosyası olarak dışa aktarabilirsiniz. Bazı araçlar bunu OpenAPI'ye dönüştürebilir.

Süreç:

1. Uygulamanızı veya istemcinizi trafiği proxy aracı üzerinden yönlendirecek şekilde yapılandırın.
2. Ana API iş akışlarınızı (giriş yapma, veri oluşturma, veri getirme vb.) çalıştırın.
3. Araç, kalıpları gözlemler ve ön bir OpenAPI belirtimi oluşturur.

Artıları:

• Eski/kara kutu API'ler için harika: Sunucudan herhangi bir kod değişikliği veya işbirliği gerektirmeden çalışır.
• Gerçek kullanıma dayalı: Gerçekte kullanılan uç noktaları ve veri şekillerini yakalar.

Eksileri:

• Eksik kalabilir: Yalnızca kayıt sırasında çağırdığınız uç noktalar için belirtimler oluşturur.
• Nüansları kaçırabilir: Tüm kısıtlamaları, isteğe bağlı alanları veya hata yanıtlarını doğru bir şekilde çıkaramayabilir.
• Kurulum yükü: Ağ trafiğini yakalamayı gerektirir ve bu, bazı ortamlarda zor olabilir.

Yöntem 3: "İstek Koleksiyonu" Yaklaşımı

Bu, genellikle geliştiriciler ve ekipler için en pratik ve verimli yöntemdir. Yalnızca istek göndermekle kalmayıp API tasarımını da anlayan gelişmiş bir API istemcisi kullanırsınız. İsteklerinizden bir koleksiyon oluşturursunuz ve araç, bunları temiz bir OpenAPI belirtimi olarak yapılandırmanıza ve dışa aktarmanıza yardımcı olur.

İşte Apidog'un gücünün parladığı nokta burasıdır. Bu iş akışı için tasarlanmıştır.

Apidog ile Nasıl Çalışır?

1. Normalde Yaptığınız Gibi İstek Gönderin: İş akışınızı değiştirmeyin. Mevcut API uç noktalarınızı test etmek ve hata ayıklamak için Apidog'u kullanın. GET, POST, PUT ve DELETE istekleri gönderdiğinizde, Apidog tüm ayrıntıları yakalar.

2. Apidog'un Modeli Oluşturmasına İzin Verin: Siz çalışırken, Apidog arka planda API'nizin yapısını anlamaya başlar. Uç noktaları, parametreleri, istek gövdelerini ve yanıt şemalarını görür.

3. Bir Belge Halinde Düzenleyin: Apidog, isteği gerçek zamanlı olarak bir API belgesine dönüştürebilir. Anlık istekleriniz, araç içinde yapılandırılmış, gezilebilir bir API belge sayfasına dönüşür. Açıklamalar ekleyebilir, uç noktaları klasörler halinde gruplayabilir ve otomatik olarak çıkarılan ayrıntıları düzenleyebilirsiniz.

4. Belirtimi Dışa Aktarın: Koleksiyonunuz doğru ve iyi tanımlanmış olduğunda, onu dışa aktarırsınız. Ardından kullanıcılar, standart YAML veya JSON formatındaki OpenAPI belirtimlerini tek tıklamayla dışa aktarabilirler. Bu belirtim, Swagger UI ile kullanılmaya, diğer araçlara aktarılmaya veya deponuza işlenmeye hazırdır.

Artıları:

• Doğal iş akışı: Geliştiricilerin zaten çalıştığı şekilde (API'leri test etme) uyum sağlar.
• Yüksek kontrol: Koleksiyonu oluştururken belirtimi düzenler ve iyileştirirsiniz.
• Kapsamlı: Tüm uç noktaların, hata yanıtlarının ve kimlik doğrulama yöntemlerinin belgelendiğinden emin olabilirsiniz.
• İşbirliğine dayalı: Ekipler aynı istek koleksiyonu üzerinde birlikte çalışabilir.

Eksileri:

• Manuel çaba gerektirir: Tüm uç noktaları kapsadığınızdan emin olmanız gerekir. Trafikten tamamen otomatik değildir.

Yöntem 4: Manuel Oluşturma Yaklaşımı

Bazen, Swagger Editor veya Stoplight Studio gibi bir düzenleyicide belirtimi elle oluşturmanız gerekir. Bu genellikle yukarıdaki yöntemlerle birlikte yapılır.

1. İstek Koleksiyonunuzu Referans Olarak Kullanın: Postman koleksiyonunuzu, cURL komutlarınızı veya Apidog projenizi ikinci bir ekranda açık tutun.
2. Belirtimi Adım Adım Oluşturun: Referanslarınızdaki her bir uç nokta için, bunu manuel olarak OpenAPI YAML/JSON'a çevirin. Bu, her parametre ve yanıt hakkında derinlemesine düşünmenizi sağlar.
3. Örneklerle Doğrulayın: Belirtiminizin gerçek API davranışıyla eşleştiğinden emin olmak için düzenleyicinin önizlemesini kullanın.

Artıları:

• Derinlemesine anlayış: Belirtiminizin her ayrıntısını bileceksiniz.
• En yüksek hassasiyet: Otomatik araçların gözden kaçırabileceği incelikleri belgeleyebilirsiniz.

Eksileri:

• Çok zaman alıcı: En çok emek gerektiren yöntem.
• Hataya açık: Yazım hatası yapmak veya uç noktaları unutmak kolaydır.

İsteklerden OpenAPI Belirtimleri Oluşturmak İçin En İyi Uygulamalar

Yönteminiz ne olursa olsun, şu prensipleri izleyin:

1. Küçük Başlayın: Bir çekirdek uç nokta seçin (örneğin GET /users). Tamamen oluşturun veya belgeleyin, sonra genişletin.
2. Erken ve Sık Sık Doğrulayın: Hemen bir sahte sunucu oluşturmak için OpenAPI belirtimini kullanın. Gerçek API'niz gibi davranıyor mu? Bu, tutarsızlıkları hızla yakalar.
3. Yineleyin ve İyileştirin: İlk oluşturduğunuz belirtim kaba olacaktır. Bunu bir taslak olarak kabul edin. Açıklamalar, örnekler ekleyin ve şema tanımlarını sıkılaştırın.
4. Hata Yanıtlarını Dahil Edin: Bu genellikle gözden kaçırılır. Belirtiminizin 4xx ve 5xx hata yanıt formatlarını belgelediğinden emin olun.
5. Kimlik Doğrulamayı Unutmayın: API'nizin nasıl güvence altına alındığını (API Anahtarı, OAuth2 vb.) securitySchemes bölümünde belgeleyin.

Sonuç: Planınız Sizi Bekliyor

Mevcut isteklerden bir OpenAPI belirtimi oluşturmak sadece mümkün olmakla kalmaz, aynı zamanda olgunlaşmış API projelerine düzen getirmek için pratik bir zorunluluktur. Kod odaklı bir kütüphane, trafik yakalama aracı veya Apidog gibi güçlü bir API istemcisi seçseniz de, netliğe, otomasyona ve işbirliğine yatırım yapmış olursunuz.

Seçtiğiniz yöntem, bağlamınıza bağlıdır: kod tabanı üzerindeki kontrol, zaman kısıtlamaları ve ekip iş akışı. Ancak amaç aynıdır: istek günlüklerinizde, cURL komutlarınızda ve sözlü bilgilerinizde bulunan örtük bilgiyi, API'nizi ileriye taşıyabilecek açık, makine tarafından okunabilir bir sözleşmeye dönüştürmek.

API'nizin karmaşıklığının gölgede kalmasına izin vermeyin. Zaten sahip olduğunuz isteklerle başlayın, doğru araçları kullanın ve o temel OpenAPI planını oluşturun. Gelecekteki kendiniz ve API'nizi kullanması gereken herkes size minnettar kalacak.