DEV Community

Cover image for CLI'dan API Tasarımı Nasıl Yapılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

CLI'dan API Tasarımı Nasıl Yapılır

Çoğu API tasarım eğitimi fareyle başlar: görsel düzenleyici açılır, şemalar tuvale sürüklenir ve alanlar diyalog kutularından eklenir. Bu yaklaşım çalışır; ancak API tanımınız Git'te yaşıyor, pull request'lerde inceleniyor ve CI'dan geçiyorsa, tasarımı da dağıtım süreciniz gibi yönetmelisiniz: terminalden, metin tabanlı ve betiklenebilir komutlarla.

Apidog'u bugün deneyin

Komut satırından API tasarlamak; sözleşmeyi oluşturmak, stil kurallarına göre lint etmek, tek dosyada demetlemek ve sunucu taslakları üretmek demektir. Her adım tekrarlanabilir, CI işlem hattında çalıştırılabilir ve ekip arkadaşları veya yapay zeka ajanları tarafından aynı komutlarla yeniden üretilebilir.

Bu rehber iki yaklaşımı ele alır:

  1. Açık kaynak araç zinciri: OpenAPI yazma, Spectral ile lint etme, Redocly CLI ile demetleme ve openapi-generator ile kod taslağı oluşturma.
  2. Apidog CLI yaklaşımı: Şemaları, uç noktaları ve kimlik doğrulamayı terminalden tek bir proje içinde yönetme.

Kavramsal arka plan için API nasıl tasarlanır ve REST API tasarlama rehberlerine bakabilirsiniz.

Apidog ile ilerleyecekseniz önce CLI'ı kurun. Apidog CLI kurulum rehberi, npm install -g apidog-cli ve apidog login --with-token adımlarını kapsar. Komut grupları için tam Apidog CLI rehberini kullanın.

Genel açık kaynak yolu: yaz, lint et, demetle, oluştur

Klasik CLI tabanlı API tasarımı, bağımsız araçları bir işlem hattında birleştirir. OpenAPI tanımını sürüm kontrolünde tutar ve her aracı ayrı bir adım olarak çalıştırırsınız. Bu, Git-tabanlı API tasarım iş akışının temelidir.

Akış şu şekildedir:

openapi.yaml
  ↓
spectral lint
  ↓
redocly bundle
  ↓
openapi-generator
Enter fullscreen mode Exit fullscreen mode

1. OpenAPI belgesini yazın

Bir openapi.yaml dosyasıyla başlayın. Özel bir editör gerekmez; herhangi bir metin editörü yeterlidir.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]
Enter fullscreen mode Exit fullscreen mode

API büyüdükçe şemaları ayrı dosyalara taşıyın ve $ref ile bağlayın. Örneğin:

components:
  schemas:
    Order:
      $ref: ./schemas/order.yaml
Enter fullscreen mode Exit fullscreen mode

Bu yapı, şemaların bağımsız okunmasını ve pull request incelemelerinin daha küçük değişiklikler üzerinden yapılmasını kolaylaştırır.

2. Spectral ile lint edin

Elle yazılan OpenAPI tanımlarında tutarsızlıklar oluşur:

  • operationId unutulabilir.
  • Bir response belgesiz kalabilir.
  • Alan adları farklı kurallarla yazılabilir.
  • Hata yanıtları eksik olabilir.

Spectral bu sorunları CI aşamasından önce yakalamanıza yardımcı olur.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Çıktıda ihlalin dosyası, satır numarası ve önem seviyesi görünür. CI'da komutun çıkış kodunu kullanarak doğrulama hatalarında build'i durdurabilirsiniz.

Örnek:

spectral lint openapi.yaml || exit 1
Enter fullscreen mode Exit fullscreen mode

Alternatif olarak Redocly CLI veya vacuum kullanabilirsiniz. Önemli olan, lint işlemini ayrı ve zorunlu bir işlem hattı adımı olarak çalıştırmaktır.

3. Redocly CLI ile demetleyin

API tanımı birden fazla dosyaya bölündüyse, kod üreticiler ve dokümantasyon araçları genellikle tek bir dosya bekler. redocly bundle, tüm $ref referanslarını çözer ve tek bir OpenAPI çıktısı üretir.

npm install -g @redocly/cli
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Artık dist/openapi.bundled.yaml dosyasını kod üretimi, dokümantasyon veya yayınlama için kullanabilirsiniz.

Redocly CLI lint işlemini de destekler:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Tüm seçenekler için Redocly CLI resmi belgelerine bakın.

4. openapi-generator ile taslak oluşturun

Lint edilmiş ve demetlenmiş OpenAPI tanımıyla sunucu taslağı veya istemci SDK'sı üretebilirsiniz.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

-g spring yerine hedefinize uygun bir jeneratör kullanın:

# Python Flask sunucusu
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g python-flask \
  -o ./server

# Go sunucusu
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g go-server \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım dört temel adımdan oluşur: yaz, lint et, demetle, oluştur. Maksimum kontrol sağlar; ancak dosya yapısını, linter kurallarını, bundle ayarlarını ve generator yapılandırmasını sizin yönetmeniz gerekir.

Apidog CLI yolu: tek bir projede tasarım

Apidog CLI yaklaşımında şemalar, uç noktalar, sahte veriler ve kimlik doğrulama tek bir proje içinde yönetilir. apidog-cli, yalnızca test çalıştırıcısı değildir; proje kaynaklarını terminalden yönetmek için komut grupları sunar:

  • schema: Veri modelleri
  • endpoint: Uç noktalar
  • folder: Organizasyon
  • security-scheme: Kimlik doğrulama
  • import / export: Tanım taşıma
  • mock: Sahte veri ve servis işlemleri

Önemli ayrım: Apidog, OpenAPI stil lint'i yapmaz ve stil rehberi uygulamaz. OpenAPI kuralları için Spectral veya vacuum kullanmaya devam etmelisiniz. Apidog ticari bir üründür ve ücretsiz katmanı bulunur. Karşılığında tasarım parçalarını tek tek bağlamak yerine, entegre bir proje modeli sunar.

Bu değiş tokuşla ilgili daha fazla bilgi için API tasarımı ve testi için Swagger alternatifleri yazısına bakın.

1. CLI'ı kurun ve kimlik doğrulayın 

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Token kurulumu için Apidog CLI kurulum rehberini kullanın.

Komutların kullanılabilir bayraklarını görmek için --help ekleyin:

apidog --help
apidog schema --help
apidog endpoint --help
Enter fullscreen mode Exit fullscreen mode

Komutlar yapılandırılmış JSON çıktısı döndürür. Çoğu yanıtta sonraki işlemleri belirten agentHints.nextSteps alanı da bulunur.

2. Veri modellerini schema ile tanımlayın

Yeniden kullanılabilir bir Order şeması oluşturmak, uç noktaların aynı sözleşmeye referans vermesini sağlar. Bu, OpenAPI'deki components/schemas yaklaşımına karşılık gelir.

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

CLI çıktısı JSON olduğu için kimlikleri jq ile alıp sonraki komutlara aktarabilirsiniz:

apidog schema list --project <PROJECT_ID> | jq
Enter fullscreen mode Exit fullscreen mode

Elinizde mevcut bir OpenAPI dosyası varsa, yeniden yazmak yerine içe aktarın:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog import, OpenAPI 3.x, Swagger 2.0, Postman ve Apidog formatlarını kabul eder. Böylece mevcut tanımınızı doğrudan proje kaynağına dönüştürebilirsiniz.

3. Uç noktaları endpoint ile tanımlayın

Modeller hazır olduğunda işlemleri ekleyin veya güncelleyin.

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Uç nokta listesini JSON olarak almak, otomasyon için kullanışlıdır. Örneğin, beklenen yolların bulunduğunu bir script ile kontrol edebilirsiniz:

apidog endpoint list --project <PROJECT_ID> | jq
Enter fullscreen mode Exit fullscreen mode

İlgili uç noktaları klasörlerle gruplayın:

apidog folder --help
Enter fullscreen mode Exit fullscreen mode

Bu, proje büyüdüğünde kaynakların daha kolay bulunmasını sağlar.

4. Kimlik doğrulamayı security-scheme ile tanımlayın

Kimlik doğrulama sözleşmenin parçasıdır. security-scheme grubu; API anahtarı, bearer token ve OAuth 2.0 gibi kimlik doğrulama mekanizmalarını proje düzeyinde tanımlamanıza yardımcı olur.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Kimlik doğrulamayı proje düzeyinde bir kez tanımlayın ve uç noktaların bu tanıma referans vermesini sağlayın. Her endpoint'te kimlik doğrulamasını tekrar yazmak sözleşme kaymasına yol açabilir.

Bu yapı OpenAPI'deki components/securitySchemes kavramıyla eşleşir; bu nedenle içe ve dışa aktarma akışı korunur.

5. CLI kaynak yazımlarını doğrulayın

Bir kaynak tanımını kaydetmeden veya CI'a göndermeden önce biçiminin geçerli olduğundan emin olun.

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Bu komutu uygulama adımından önce çalıştırın:

apidog cli-schema validate --file resource.json \
  && echo "Kaynak tanımı geçerli"
Enter fullscreen mode Exit fullscreen mode

Sıfır olmayan çıkış kodu, hatalı kaynakların projeye uygulanmasını engeller.

apidog cli-schema validate, OpenAPI stil lint'i değildir. CLI kaynak yapısını doğrular. OpenAPI stil ve kural ihlalleri için Spectral veya vacuum kullanın.

6. OpenAPI'ye geri aktarın

Apidog içinde tasarım yaptıktan sonra taşınabilir bir OpenAPI çıktısı üretebilirsiniz.

mkdir -p dist

apidog export \
  --project <PROJECT_ID> \
  --format openapi \
  -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dışa aktarılan OpenAPI dosyasını diğer araçlara aktarabilirsiniz:

spectral lint dist/openapi.yaml

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Apidog projesi ile açık kaynak araç zinciri birbirini dışlamaz. apidog export, iki yaklaşım arasındaki köprüdür.

CI'a entegre etme

Her iki yaklaşım da CI için uygundur çünkü komutlar standart çıktı ve çıkış kodu üretir. Minimal bir kontrol adımı şöyle olabilir:

# OpenAPI stil ihlallerinde başarısız ol
spectral lint openapi.yaml

# Uygulamadan önce CLI kaynak tanımını doğrula
apidog cli-schema validate --file resource.json

# Alt araçlar için tek bir OpenAPI yapıtı üret
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Bu akışı bir GitHub Actions, GitLab CI veya başka bir CI ortamına doğrudan ekleyebilirsiniz. Temel sıralama şudur:

  1. OpenAPI tanımını lint edin.
  2. Apidog kaynak dosyalarını doğrulayın.
  3. OpenAPI dosyasını bundle edin.
  4. İsteğe bağlı olarak kod veya dokümantasyon üretin.

Apidog komutları agentHints.nextSteps içeren JSON döndürdüğü için akış, yapay zeka kodlama ajanları tarafından da yönlendirilebilir. Ajan, çıktıdaki önerilen sonraki adımı okuyup terminal komutunu çalıştırabilir; GUI otomasyonu gerekmez.

Sık karşılaşılan sorunlar

Bölünmüş dosyalar alt araçları bozar

Birçok $ref dosyasına ayrılmış OpenAPI tanımı insanlar için okunabilir olabilir; ancak kod üreticiler ve belge araçları tek dosya bekleyebilir.

Kod üretmeden veya dokümantasyon yayınlamadan önce demetleyin:

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog'un lint yapmasını beklemek

Apidog kaynakları yönetir; OpenAPI stil rehberi uygulamaz ve stil ihlallerini işaretlemez.

Bu nedenle işlem hattında Spectral veya vacuum kullanın:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ayrıca apidog cli-schema validate komutunu linter olarak değerlendirmeyin. Bu komut CLI kaynak biçimini doğrular; OpenAPI stilini değil.

Düzenlemeden önce içe aktarmayı unutmak

Mevcut bir API'yi Apidog CLI üzerinden düzenlemek istiyorsanız önce tanımı projeye aktarın:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Boş bir projede çalışmak, mevcut uç noktaların otomatik olarak görünmesini sağlamaz.

Kimlik doğrulamayı uç nokta başına yeniden tanımlamak

Kimlik doğrulamayı proje düzeyinde security-scheme olarak tanımlayın. Ardından uç noktaların bu tanıma referans vermesini sağlayın. Her işlemde aynı kimlik doğrulama ayrıntılarını tekrar etmek, zamanla tutarsızlık oluşturur.

Özet

CLI tabanlı API tasarımı, GUI tıklamalarını tekrarlanabilir ve otomasyona uygun komutlara dönüştürür.

Açık kaynak yaklaşımı:

OpenAPI yaz
→ Spectral ile lint et
→ Redocly ile bundle et
→ openapi-generator ile üret
Enter fullscreen mode Exit fullscreen mode

Bu yol maksimum kontrol sağlar ve Git tabanlı süreçlere iyi uyar.

Apidog CLI yaklaşımı ise şemaları, uç noktaları ve kimlik doğrulamayı tek bir proje içinde yönetir. Dışa aktarma özelliği sayesinde OpenAPI yapıtını yine Spectral, Redocly veya openapi-generator gibi araçlara aktarabilirsiniz.

Ekibiniz zaten bağımsız CLI araçlarıyla çalışıyorsa bu zinciri koruyun. Tek bir proje içinde yönetilen tasarım kaynakları istiyorsanız, Apidog'u indirin, CLI'ı kurun ve sonraki API'nizi terminalden tasarlayın.

Top comments (0)