Swagger CLI'dan Apidog CLI'a Nasıl Geçilir

Pipeline'ınızda hala swagger-cli validate ve swagger-cli bundle kullanıyorsanız, kimsenin artık bakımını yapmadığı bir aracın etrafında bir betik sürdürüyorsunuz demektir. swagger-cli GitHub deposu artık bunu doğrudan belirtiyor: paket artık bakımı yapılmıyor, README, çok az katkı sağlayan geniş bir kullanıcı tabanına ayak uydurmanın yükünden bahsediyor ve yeni kullanıcıları başka yere yönlendiriyor.

Bu nedenle, belirtim iş akışınızın bundan sonra nerede yaşayacağına karar vermek için iyi bir an. Bu rehber bir geçiş el kitabı, bir kullanım eğitimi değil. Taşınmaya hazır değilseniz ve sadece eski aracı kullanmaya devam etmek istiyorsanız, Swagger CLI rehberi validate ve bundle konularını ayrıntılı olarak ele alıyor. Bu makale, özellikle CI'ınızı bozmadan Swagger CLI'dan Apidog CLI'a nasıl geçileceği hakkındadır.

Gerçek komutları takip etmek isterseniz Apidog'u indirin. Başlamak ücretsizdir, kredi kartı gerekmez.

Neden şimdi geçiş yapmalı?

Önce dürüst cevap: swagger-cli bir süredir kullanımdan kaldırıldı ve bakımı yapılmıyor. Hala çalışıyor. Birçok pipeline bugün onu çağırıyor. Ancak hata düzeltmeleri veya belirtim güncellemeleri alamayacak bir araç, derlemenizde oturan teknik bir borçtur ve bakımcılar da kendileri ilerlemeyi öneriyor.

Özellikle bir halef işaret ediyorlar. Terminalde yalnızca doğrulama ve paketleme istiyorsanız, Redocly CLI en yakın doğrudan değiştirmedir. Açık kaynaklı, kod odaklı ve terminal yerelidir. lint komutu yapısal doğrulama yapar ve redocly bundle, swagger-cli bundle gibi $ref işaretçilerini tam olarak takip eder. Tek amacınız belirtimi deponuzda düz bir dosya olarak tutan 1:1 bir değişim ise, Redocly doğal bir seçimdir ve Redocly, komut eşlemesiyle birlikte kendi geçiş rehberini yayınlar. Bu yolu seçmekten utanılacak bir şey yok.

Apidog farklı bir amaç içindir. Belirtimin bir dosyada durmaktan daha fazlasını yapmasını istediğinizde Apidog CLI'ya geçin. Statik bir belgeyi doğrulamak ve paketlemek yerine, tüm tanımı canlı bir çalışma alanına getirir, ardından içe aktarırken doğrular, ihtiyacınız olduğunda birleştirilmiş bir dosya dışa aktarır ve isteğe bağlı olarak API'yi taklit eder, ona karşı test senaryoları çalıştırır ve aynı kaynaktan belgeler yayınlar. swagger-cli yalnızca iki şey yapardı. Apidog yaşam döngüsünün geri kalanını kapsar.

Hype'a göre değil, uygunluğa göre seçin. Yalnızca terminalden çalıştırdığınız hafif, yapılandırma odaklı bir linter ve paketleyici istiyorsanız, Redocly kazanır. Birkaç aracı bir araya getirmek yerine tasarım, taklit, test ve belgeler için tek bir platforma sahip olmak istiyorsanız, Apidog kazanır.

swagger-cli ne yapardı, Apidog CLI ne yapar

swagger-cli'nin tam olarak iki komutu vardı:

• swagger-cli validate <dosya> bir Swagger 2.0 veya OpenAPI 3.0 belgesini şemaya göre kontrol eder ve $ref işaretçilerinin çözümlendiğini doğrular.
• swagger-cli bundle <dosya> bu $ref işaretçilerini takip eder ve çok dosyalı bir tanımı tek bir dosyada birleştirir, çıktı yolu (-o), tür (-t json|yaml), tam referanssızlaştırma (-r) ve girinti (-f) seçenekleriyle.

Aracın tamamı buydu. Stil kurallarıyla lint yapmaz, belge oluşturmaz, test çalıştırmaz veya herhangi bir şeyi taklit etmezdi.

Apidog CLI bu iki işi iki komutuna eşler, ardından devam eder:

• apidog import bir tanımı bir Apidog projesine alır ve içeri alırken doğrular. Çok dosyalı belirtimlerin $ref işaretçileri otomatik olarak birleştirilmiş kaynaklara çözümlenir. Bu, doğrulama adımınız artı alım işleminizdir.
• apidog export projeden tek bir birleştirilmiş dosya çıkarır ve dışa aktarırken OpenAPI sürümünü seçmenize olanak tanır. Bu, paketleme adımınız artı isteğe bağlı bir sürüm yükseltme ve HTML veya Markdown belgeleri oluşturma yeteneğidir.
• apidog run, CI için JUnit ve diğer raporlayıcılarla test senaryolarını ve süitlerini yürütür. swagger-cli'nin eşdeğeri yoktu.
• Kaynak komutları (endpoint, schema, mock, environment, branch ve daha fazlası) belirtim projeye alındıktan sonra projeyi terminalden yönetir.

Eşlemenin dürüst kalması için önemli bir nokta: Apidog içe aktarırken yapıyı doğrular, ancak yapılandırılabilir bir stil rehberi linter'ı değildir. Bir apidog lint komutu veya özel kural kümeleri yoktur. Eğer görüşe dayalı linting'e güveniyorsanız, bu kısım aktarılmaz ve Neler Kazanırsınız bölümü bununla nasıl başa çıkılacağını kapsar.

Kurulum ve giriş

Apidog CLI bir npm paketi olarak gönderilir. Genel olarak kurun:

npm install -g apidog-cli@latest

Ardından bir erişim belirteci ile kimlik doğrulayın:

apidog login --with-token <TOKEN>

Belirteci Apidog uygulamasından veya web'den alırsınız: avatarınıza tıklayın, Hesap Ayarları'na, ardından API Erişim Belirteci'ne gidin ve bir tane oluşturun. CLI bunu ~/.apidog/config.toml'da saklar. Ona diğer sırlar gibi davranın. Günlüklere yazdırmayın veya deponuza kaydetmeyin.

Her bayrağı ve daha derinlemesine bir turu isterseniz, Apidog CLI eksiksiz rehberi ve resmi Apidog CLI belgeleri tam yüzeyi kapsar. Bu geçiş için, kurulum ve giriş başlamak için ihtiyacınız olan tek şeydir.

Komut eşleme tablosu

İşte swagger-cli'den Apidog CLI'a doğrudan çeviri. Tek yapısal fark: Apidog bir proje üzerinde çalışır, bu nedenle çoğu akış, tek bir komutla rastgele bir dosya üzerinde çalışmaktan ziyade içe aktarma-dışa aktarma şeklindedir.

Geçiş için en önemli iki hücre ilk iki satırdır. Onların altındaki her şey swagger-cli'nin hiç sahip olmadığı yeteneklerdir. --oas-version bayrağı en açık yükseltmedir: swagger-cli bir Swagger 2.0 dosyasını paketleyebilirdi, ancak onu OpenAPI 3.1'e dönüştüremezdi. Apidog, dışa aktarırken bunu yapabilir, bu da eski bir sözleşmeyi modernize ederken kullanışlıdır. Amacınız özellikle belge çıktısı ise, OpenAPI'yi Markdown'a dışa aktarma bu formatı daha derinlemesine ele alır.

Adım adım geçiş

İşte bir swagger-cli kurulumundan çalışan bir Apidog akışına giden tam yol.

1. Proje kimliğinizi alın. Apidog uygulamasında bir proje oluşturun veya açın. Proje kimliği proje ayarlarında ve URL'de görünür. Bunu her CLI komutuna --project aracılığıyla ileteceksiniz.

2. Kök belirtimi içe aktarın. Apidog'u tanımınızın giriş dosyasına yönlendirin. $ref işaretçili çok dosyalı belirtimler otomatik olarak çözümlenir, böylece kökünü içe aktarırsınız ve Apidog geri kalanını çeker:

apidog import --project 123456 --format openapi --file ./openapi.yaml

Belirtim yanlış biçimlendirilmişse veya bir $ref asılı kalmışsa, içe aktarma başarısız olur. Bu başarısızlık sizin doğrulama kapınızdır, swagger-cli validate'ın yaptığı aynı iş, şimdi alıma dahil edilmiştir.

3. Uygulamada doğrulayın. Projeyi açın ve uç noktalarınızın, şemalarınızın ve parametrelerinizin doğru şekilde yerleştiğini onaylayın. Bu görsel kontrolün swagger-cli eşdeğeri yoktur ve içe aktarmanın beklediğiniz şeyi yaptığını doğrulamak için geçiş sırasında bir kez yapmaya değerdir.

4. Birleştirilmiş dosyayı dışa aktarın. Tek bir düz dosyaya ihtiyacınız olduğunda (aşağı akış aracı, istemci oluşturucu veya bir yapıt için), dışa aktarın. İstediğiniz OpenAPI sürümünü seçin:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Bu, swagger-cli bundle yerine geçer. $ref işaretçileri zaten içe aktarmada çözümlenmişti, bu nedenle dışa aktarma sizin birleştirilmiş, tek dosyalı çıktınızdır.

5. CI'a bağlayın. Eski swagger-cli adımınızı içe aktarma (alım sırasında doğrulama) ve dışa aktarma (paketleme) ile değiştirin ve senaryolarınız varsa bir test çalıştırması ekleyin. Bir sonraki bölümde tam bir GitHub Actions örneği bulunmaktadır.

GitHub Actions ile CI örneği

Bu iş akışı CLI'ı kurar, depo sırlarından bir belirteçle giriş yapar, belirtimi doğrulamak için içe aktarır, birleştirilmiş bir yapıtı dışa aktarır, ardından JUnit raporlayıcısıyla test senaryolarını çalıştırır, böylece başarısız bir test kontrolü başarısız kılar ve PR'yi engeller.

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Belirteci depo sırlarınızda APIDOG_ACCESS_TOKEN olarak saklayın, böylece asla günlüklerde görünmez. -r "cli,junit" raporlayıcısı, CI'nizin bir test raporu olarak gösterebileceği bir JUnit XML dosyası yazar ve başarısız bir senaryo, birleşmeyi engelleyen sıfır olmayan bir çıkış kodu döndürür. Daha derin pipeline desenleri için Apidog CLI CI/CD rehberine ve çalıştırıcıya özel kurulum için GitHub Actions ile Apidog CLI kılavuzuna bakın.

Doğrulama ve paketlemeden fazlası: Neler kazanırsınız

İşte geçişin karşılığını verdiği ve dürüst olmanın en önemli olduğu yer burası.

Mock sunucuları. Belirtiminiz bir projeye girdiğinde, Apidog ondan sahte yanıtlar sunabilir. Backend henüz mevcut değilken API'ye karşı bir frontend geliştirebilirsiniz. swagger-cli hiçbir zaman çalışma zamanı davranışına dokunmadı.

Otomatik test senaryoları. apidog run, çalışan bir API'ye karşı gerçek istekleri yürütür ve yanıtları doğrular. Senaryoları uygulamada görsel olarak oluşturur, ardından bunları CI'da başsız olarak çalıştırırsınız. Bu, swagger-cli'nin açık bıraktığı boşluğu kapatır: geçerli bir belirtim, sözleşmenin iyi biçimlendirilmiş olduğunu söyler, uygulamanın ona uygun olduğunu değil.

Barındırılan ve dışa aktarılan belgeler. apidog export --format html veya --format markdown, aynı kaynaktan doğrudan belgeler üretir. Bakımı yapılacak ayrı bir belge oluşturma adımı yoktur.

Şimdi dürüst sınıra gelelim. Apidog CLI, özel kural kümelerine sahip yapılandırılabilir, kod öncelikli bir stil kılavuzu linter'ına sahip değildir. İçe aktarırken yapıyı doğrular, ancak CLI aracılığıyla Spectral tarzı veya Redocly tarzı kurallar yazamazsınız ve bir apidog lint komutu yoktur. Eski kurulumunuz yoğun linting'e (tutarlı adlandırma, gerekli açıklamalar, her yanıtta örnekler) dayanıyorsa, özel bir linter'ı döngüde tutun. Bunun için Apidog'u Spectral veya Redocly ile eşleştirin ve bunu ayrı bir CI adımı olarak çalıştırın. OpenAPI linter kurulum rehberi, bir tanesinin nasıl bağlanacağını kapsar. Her ikisini de kullanmak bir çelişki değildir: uzman bir araçla lint yapın, ardından yaşam döngüsünü Apidog'da yönetin.