Apidog'un API'ler modülünde aynı API sözleşmesini oluşturmak için iki çalışma yüzeyi kullanabilirsiniz: görsel formlarla çalışan Tasarım Öncelikli Mod ve Git'e bağlı ham OpenAPI/Swagger dosyasıyla çalışan Spesifikasyon Öncelikli Mod. İkisi de geçerli OpenAPI üretir; fark, sözleşmeyi nasıl yazdığınız, nasıl gözden geçirdiğiniz ve Git iş akışınıza nasıl dahil ettiğinizdir.
Bu rehberde Apidog'da tasarım öncelikli ve spesifikasyon öncelikli yaklaşımı pratik açıdan karşılaştıracağız: hangi mod ne yapar, Git ile nasıl çalışır, hangi ekipler için daha uygundur ve modlar arasında nasıl geçiş yapılır. API'ler modülünün sol alt köşesindeki tek düğmeyle mod değiştirebilirsiniz; bu yüzden seçim kalıcı değildir. Ancak doğru varsayılanı seçmek ekip içi sürtünmeyi azaltır.
İki yaklaşım: aynı sözleşme, farklı düzenleme yüzeyi
Her iki yaklaşımın ortak kuralı şudur:
Uygulamayı yazmadan önce API sözleşmesini tanımlarsınız.
Bu sözleşme; backend implementasyonu, testler, mock sunucular ve dokümantasyon için doğruluk kaynağıdır.
Tasarım öncelikli nedir?
Tasarım öncelikli yaklaşımda API sözleşmesini yapılandırılmış bir arayüz üzerinden oluşturursunuz.
Örneğin:
- HTTP metodu seçersiniz:
GET,POST,PUT - Path tanımlarsınız:
/users/{id} - Query/path parametreleri eklersiniz
- Request ve response şemalarını form veya ağaç düzenleyiciyle oluşturursunuz
- Örnek yanıtlar tanımlarsınız
OpenAPI çıktısını Apidog arka planda üretir. Bu nedenle YAML sözdizimiyle uğraşmadan sözleşme tasarlayabilirsiniz.
Spesifikasyon öncelikli nedir?
Spesifikasyon öncelikli yaklaşımda sözleşmeyi doğrudan OpenAPI veya Swagger dosyası olarak yazarsınız.
Örnek:
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Kullanıcı detayını getir
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Başarılı yanıt
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
Bu modelde spesifikasyon dosyası, kaynak kod gibi ele alınır: Git'te tutulur, pull request ile incelenir ve satır satır karşılaştırılır.
Bu ayrımı kod öncelikli yaklaşımla karıştırmamak gerekir. Kod öncelikli geliştirmede spesifikasyon, uygulama kodundaki açıklamalardan üretilir. Apidog'daki iki modda ise sözleşme koddan önce gelir. Sadece sözleşmeyi yazma biçiminiz değişir.
Spesifikasyonunuzu sürümlü bir yapıt olarak yönetme yaklaşımı için Git-yerel API iş akışı yazısına da bakabilirsiniz.
Apidog Tasarım Öncelikli Modu
Tasarım Öncelikli Mod, API sözleşmesini görsel arayüzle oluşturmak isteyen ekipler içindir. Uç noktaları, parametreleri, şemaları ve örnekleri formlar üzerinden tanımlarsınız. Apidog arka planda OpenAPI dokümanını üretir.
Bu mod özellikle şu durumlarda kullanışlıdır:
- Ekipte OpenAPI sözdizimine hâkim olmayan kişiler varsa
- Ürün, QA ve backend ekipleri aynı sözleşmeyi birlikte gözden geçiriyorsa
- Yeni bir API'yi hızlıca tasarlamak istiyorsanız
- Şema hatalarını manuel YAML düzenlemeyle yakalamak istemiyorsanız
Örneğin bir Error şemasını tekrar kullanılabilir bileşen olarak tanımlayıp farklı endpoint yanıtlarında kullanabilirsiniz. Bunu ham YAML içinde elle $ref yazarak yapmak yerine arayüzden seçebilirsiniz.
Tasarım Öncelikli Mod ayrıca branch desteği sunar. Böylece ekipler aynı API'nin farklı tasarım varyasyonları üzerinde paralel çalışabilir ve daha sonra değişiklikleri uzlaştırabilir.
Avantajı:
- OpenAPI sözdizimi bilmeden API tasarlayabilirsiniz
- Geçersiz alanlar veya hatalı şema yapıları daha erken yakalanır
- Yapılandırılmış diff, teknik olmayan paydaşlar için daha okunabilirdir
Dezavantajı:
- OpenAPI'yi zaten elle yazmaya alışkınsanız formlar ekstra tıklama gibi gelebilir
Apidog Spesifikasyon Öncelikli Modu
Spesifikasyon Öncelikli Mod şu anda beta aşamasındadır. Bu modda API sözleşmesini doğrudan YAML veya JSON olarak yazarsınız. Apidog size IDE benzeri bir kod düzenleyici sunar.
Düzenleyici şu özellikleri destekler:
- Sözdizimi vurgulama
- Satır içi doğrulama
- OpenAPI ve Swagger şemalarına göre otomatik tamamlama
- Sol kenar çubuğunda path ve component taslağı
- Git senkronizasyon durum göstergesi
Bu mod, API sözleşmesini doğrudan Git deposunda yönetmek isteyen ekipler için uygundur.
Tipik iş akışı şöyle görünür:
- GitHub, GitLab veya Azure DevOps deponuzu bağlayın.
- OpenAPI/Swagger dosyanızı Apidog'da açın.
- YAML veya JSON dosyasını düzenleyin.
- Apidog içinden commit ve push yapın.
- Alternatif olarak dosyayı kendi IDE'nizde değiştirip Git'e push edin.
- Değişiklikleri Apidog'a geri senkronize edin.
Örnek Git odaklı kullanım:
git checkout -b update-user-api
# openapi.yaml dosyasını düzenleyin
git add openapi.yaml
git commit -m "Update user detail response schema"
git push origin update-user-api
Ardından aynı değişiklikleri Apidog üzerinden görüntüleyebilir, test ve dokümantasyon akışlarında kullanabilirsiniz.
Git entegrasyonu hakkında detaylar için Spesifikasyon Öncelikli Mod belgelerini inceleyebilirsiniz.
Bu yaklaşım, API sözleşmesini diğer kod yapıtlarıyla aynı şekilde yöneten ekipler için uygundur:
- Pull request ile API değişikliği inceleme
- CI içinde OpenAPI doğrulaması yapma
- Sözleşmeyi servis koduyla birlikte sürümleme
- Araçlar arasında tek bir standart
openapi.yamldosyası kullanma
Bu modelin arkasındaki mantık için kod olarak API spesifikasyonu yazısına bakabilirsiniz.
Yan yana karşılaştırma
İki mod da aynı OpenAPI sözleşmesini üretir. Fark, sözleşmeyi nasıl düzenlediğiniz ve nasıl sürümlendirdiğinizdir.
| Özellik | Tasarım Öncelikli Mod | Spesifikasyon Öncelikli Mod |
|---|---|---|
| Düzenleyici | Görsel formlar ve şema ağacı | IDE tarzı YAML/JSON düzenleyici |
| Spesifikasyon formatı | OpenAPI arka planda oluşturulur | OpenAPI/Swagger elle yazılır |
| Git iş akışı | Apidog içinde branch desteği | GitHub, GitLab ve Azure DevOps ile iki yönlü senkronizasyon |
| Doğrulama | Form girişleriyle zorlanır | Satır içi sözdizimi doğrulama ve otomatik tamamlama |
| Navigasyon | Endpoint listesi ve klasörler | Sol kenar çubuğunda otomatik ayrıştırılmış taslak |
| Öğrenme eğrisi | Düşük | Daha yüksek; OpenAPI bilgisi gerekir |
| En uygun ekip | Karma yetkinlikte ekipler | Spesifikasyonu kod olarak yöneten mühendislik ekipleri |
Hangi modu seçmelisiniz?
Tasarım Öncelikli Mod'u seçin, eğer:
- Ekibinizde OpenAPI uzmanı olmayan kişiler varsa
- Ürün yöneticileri veya QA ekipleri sözleşmeyi inceleyecekse
- Yeni API'leri hızlıca tasarlamak istiyorsanız
- YAML hatalarıyla zaman kaybetmek istemiyorsanız
- API tasarımını görsel ve yapılandırılmış şekilde tartışmak istiyorsanız
Örnek senaryo:
Bir kullanıcı yönetimi API'si tasarlıyorsunuz. Ürün ekibi alan adlarını, QA ekibi hata yanıtlarını, backend ekibi şema detaylarını gözden geçiriyor. Bu durumda görsel tasarım yüzeyi daha hızlı ortak anlayış sağlar.
Spesifikasyon Öncelikli Mod'u seçin, eğer:
- OpenAPI dosyanız zaten Git deposunda yaşıyorsa
- API değişikliklerini pull request üzerinden inceliyorsanız
- CI/CD içinde spesifikasyon doğrulaması yapıyorsanız
- Servis kodu ve API sözleşmesini aynı repoda tutmak istiyorsanız
- YAML/JSON ile çalışmak ekibiniz için doğal bir iş akışıysa
Örnek senaryo:
Backend ekibiniz openapi.yaml dosyasını servis deposunda tutuyor. Her API değişikliği pull request ile geliyor ve CI içinde doğrulanıyor. Bu durumda Spesifikasyon Öncelikli Mod, Apidog'u ayrı bir doğruluk kaynağı yapmaz; aynı dosyaya erişen ek bir çalışma yüzeyi haline getirir.
Pratik orta yol
Birçok ekip şu modeli kullanabilir:
- Yeni endpoint'leri Tasarım Öncelikli Mod'da hızlıca tasarlar.
- Şemaları ve örnek yanıtları netleştirir.
- API olgunlaştığında Spesifikasyon Öncelikli Mod'a geçer.
- Sözleşmeyi Git tabanlı inceleme sürecine dahil eder.
Bu iki mod rakip değildir. Aynı API sözleşmesinin iki farklı görünümüdür.
Modlar nasıl değiştirilir?
Apidog'da mod değiştirmek için:
- Projenizi açın.
- API'ler modülüne gidin.
- Sol alt köşedeki mod değiştiriciyi bulun.
- Tasarım Öncelikli veya Spesifikasyon Öncelikli Mod'u seçin.
Geçiş yaptığınızda aynı sözleşme diğer düzenleme yüzeyinde açılır.
Dikkat edilmesi gerekenler:
- Endpoint'ler, şemalar ve örnekler korunur.
- API'yi yeniden oluşturmazsınız; sadece düzenleme biçimini değiştirirsiniz.
- Spesifikasyon Öncelikli Mod'da Git senkronizasyonu için önce GitHub, GitLab veya Azure DevOps bağlantısı kurmanız gerekir.
- Spesifikasyon Öncelikli Mod beta aşamasında olduğu için üretim sözleşmelerinde kullanmadan önce küçük bir projede senkronizasyon davranışını test etmek iyi bir fikirdir.
SSS
Spesifikasyon öncelikli, sözleşme öncelikli ile aynı mı?
Pratikte evet. İki yaklaşım da API sözleşmesini uygulamadan önce yazmayı ve bu sözleşmeyi doğruluk kaynağı olarak kabul etmeyi ifade eder.
Apidog'daki Spesifikasyon Öncelikli Mod, sözleşmenin Git ile senkronize edilen elle yazılmış bir OpenAPI veya Swagger dosyası olduğu sözleşme öncelikli bir iş akışıdır.
Spesifikasyon Öncelikli Mod GitLab ve Azure DevOps ile çalışır mı?
Evet. Spesifikasyon Öncelikli Mod, GitHub ve GitLab ile doğrudan iki yönlü Git senkronizasyonunu destekler. Azure DevOps ise genel Git Bağlantısı üzerinden kullanılabilir.
Tasarım Öncelikli Mod'dan Spesifikasyon Öncelikli Mod'a geçerken verilerim kaybolur mu?
Hayır. Her iki mod da aynı temel API sözleşmesini okur ve yazar. Sol alttaki mod değiştiriciyi kullandığınızda endpoint'leriniz, şemalarınız ve örnekleriniz korunur.
Değişen şey veri değil, düzenleme yüzeyidir.
Sonuç
Ekibinizin nasıl çalıştığına göre varsayılan modu seçin:
- Görsel tasarım, düşük öğrenme eğrisi ve ekipler arası iş birliği istiyorsanız Tasarım Öncelikli Mod kullanın.
- OpenAPI dosyasını Git'te, pull request ve CI süreçleriyle yönetmek istiyorsanız Spesifikasyon Öncelikli Mod kullanın.
Kararsızsanız bir sonraki endpoint'inizi iki modda da deneyin. Sözleşme aynı kalır; önemli olan ekibinizin en az sürtünmeyle çalıştığı yüzeyi seçmektir.
Top comments (0)