Çoğu API tasarım eğitimi bir fareyle başlar. Görsel bir düzenleyici açın, bir şemayı tuvale sürükleyin, bir alan eklemek için diyalogları tıklayın. Bu işe yarar, ancak birçok ekibin aslında ürünleri nasıl yayınladığına uymuyor. API tanımınız Git'te yaşıyorsa, çekme isteklerinde inceleniyorsa ve sürekli entegrasyondan (CI) geçiyorsa, onu dağıttığınız şekilde tasarlamak istersiniz: terminalden, metin olarak, betikleyebileceğiniz komutlarla.
Komut satırından API tasarlamak, sözleşmeyi oluşturmanız, bir stil rehberine göre lint etmeniz, tek bir dosyada demetlemeniz ve taslaklar oluşturmanız anlamına gelir, tüm bunlar kabuktan ayrılmadan gerçekleşir. Her adım tekrarlanabilir. Her adım bir işlem hattında çalışabilir. Ve bir yapay zeka aracısının veya bir ekip arkadaşınızın kurulumunuzu yeniden üretmesi gerektiğinde, hangi düğmelere tıkladığınızı tahmin etmek yerine sizin yaptığınız komutların aynısını çalıştırırlar.
Bu rehber iki yolu ele alıyor. İlk olarak, tek amaçlı araçlardan oluşan genel açık kaynak yolu: bir OpenAPI dosyası yazmak, onu Spectral ile lint etmek, Redocly CLI ile demetlemek ve openapi-generator ile sunucu taslakları oluşturmak. Ardından, tasarım, şemalar, uç noktalar ve kimlik doğrulamanın terminalden yönetebileceğiniz tek bir projede bulunduğu Apidog CLI yolu. Önce daha derin kavramsal arka planı istiyorsanız, bir API nasıl tasarlanır rehberimizi ve REST API'leri tasarlama kılavuzunu okuyun.
düğme
Apidog ile takip ediyorsanız, önce ikili dosyayı edinin. Apidog CLI kurulum rehberimiz npm install -g apidog-cli adımını ve apidog login --with-token el sıkışmasını kapsar ve tam Apidog CLI rehberi her komut grubunu haritalar.
Genel açık kaynak yolu: yaz, lint et, demetle, oluştur
Klasik CLI tasarım yığını, birbirine bağladığınız bağımsız araçlardan oluşan bir settir. API tanımınızı bir OpenAPI dosyasında sürüm kontrolü altında tutar ve her aracı bir adım olarak çalıştırırsınız. Bu, Git-tabanlı API tasarım iş akışıdır ve gerçekten iyidir. İşte genel şekli.
OpenAPI belgesini yazın
Düz bir YAML dosyasıyla başlarsınız. Özel bir düzenleyici gerekmez; herhangi bir metin düzenleyici iş görür. Minimal bir openapi.yaml şöyle görünür:
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]
API büyüdükçe, onu birden çok dosyaya böler ve $ref ile referans verirsiniz. Bu, her şemanın kendi başına okunabilir ve incelenebilir kalmasını sağlar.
Spectral ile Lint Etme
Elle yazılan OpenAPI kaymaları oluşabilir. Biri bir operationId'yi unutur, bir başkası bir yanıtı belgesiz bırakır, üçüncüsü kendi adlandırma kuralını icat eder. Bir linter, tüm bunları incelemeden önce yakalar. Stoplight'tan Spectral, standart bir seçimdir. OpenAPI için kural kümeleriyle birlikte gelir ve kendi kurallarınızı yazmanıza olanak tanır.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral her ihlali bir satır numarası ve ciddiyet derecesiyle yazdırır. CI'da çıkış kodunu kontrol ederek hatalarda derlemeyi başarısız edebilirsiniz. Alternatif isterseniz Redocly CLI ve vacuum da aynı işi yapar; vacuum hızlıdır ve Spectral uyumlu bir linter olarak kolayca entegre olur. Hangisini seçerseniz seçin, önemli olan şudur: lint etme ayrı, özel bir araçtır ve onu kendi başına bir adım olarak çalıştırırsınız.
Redocly CLI ile Demetleme
Tanımınız dosyalar arasında bölündüğünde, çoğu alt araç tek, kendi kendine yeten bir belge ister. Redocly CLI her $ref'i çözer ve ağacı tek bir dosyaya düzleştirir.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly ayrıca lint eder (redocly lint) ve belgeleri önizler, bu nedenle bazı ekipler hem stil kontrolü hem de demetleme için bunu kullanır. Resmi belgeleri tüm komut setini listeler.
openapi-generator ile Taslaklar Oluşturma
Temiz, demetlenmiş bir belirtimle kod üretirsiniz. openapi-generator, bir OpenAPI belgesini düzinelerce dilde sunucu taslaklarına, istemci SDK'larına ve daha fazlasına dönüştürür.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
-g spring'i -g python-flask, -g go-server veya desteklenen herhangi bir jeneratörle değiştirin. Artık sözleşmenize tam olarak uyan bir iskeletiniz var.
Açık yol baştan sona budur: dört araç, dört komut, hepsi betiklenebilir. Maliyeti kablolamadır. Dosya düzenini, linter yapılandırmasını, demetleme adımını ve jeneratör yapılandırmasını kendiniz sürdürürsünüz ve her aracın kendi kuralları vardır. Maksimum kontrol istediğinizde ve yapıştırmayı sorun etmediğinizde iyi çalışır.
Apidog CLI yolu: tek bir projede tasarım
Diğer yaklaşım, tasarım, şemalar, uç noktalar, sahte veriler ve kimlik doğrulamayı terminalden yönettiğiniz tek bir proje içinde tutar. apidog-cli ikili dosyası sadece bir test çalıştırıcısı değil, tam bir proje kaynak CLI'sidir. Tüm tasarım yüzeyi için komut gruplarına sahiptir: veri modelleri için schema, işlemler için endpoint, organizasyon için folder, kimlik doğrulama için security-scheme, ayrıca import, export, mock ve daha fazlası.
Dürüst bir not: Apidog, OpenAPI'nizi lint etmez veya bir stil rehberini uygulamaz. Amacı bu değildir. Lint etmeye ihtiyacınız varsa, işlem hattınızda Spectral veya vacuum'u tutun. Apidog da açık kaynak değildir; ücretsiz bir katmanı olan ticari bir üründür. Size verdiği şey entegre bir projedir, böylece tasarım parçalarını kendiniz bir araya getirmek zorunda kalmazsınız. API tasarımı ve testi için Swagger alternatifleri hakkındaki görüşümüz, bu değiş tokuşun nerede mantıklı olduğunu ele alır.
Önce kurun ve kimlik doğrulayın (token kurulumu için kurulum rehberine bakın):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Her komut yapılandırılmış JSON döndürür ve çoğu yanıt, bir sonraki neyi çalıştırmanız gerektiğini size (veya bir aracıya) söyleyen bir agentHints.nextSteps bloğu içerir. Kesin bayraklarını görmek için herhangi bir komuta --help ekleyin.
apidog şeması ile veri modellerini tanımlayın
Tasarım verilerinizle başlar. Yeniden kullanılabilir bir Order şeması, uç noktaların referans aldığı tek doğru kaynak haline gelir; bu, ham OpenAPI'deki components/schemas ile aynı fikirdir, ancak bir proje kaynağı olarak yönetilir.
apidog schema --help
apidog schema create --project <PROJECT_ID>
Çıktı JSON olduğundan, yeni şemanın kimliğini almak ve bir sonraki komuta beslemek için onu jq aracılığıyla yönlendirebilirsiniz. Zaten bir OpenAPI dosyanız varsa, her şeyi yeniden yazmak yerine onu içe aktarın:
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog import, OpenAPI 3.x, Swagger 2.0, Postman ve Apidog formatlarını kabul eder, böylece mevcut bir tanım tek bir adımda canlı bir proje haline gelir.
apidog uç noktası ile uç noktaları tanımlayın
Modeller yerleştirildikten sonra işlemleri eklersiniz. endpoint grubu, uç noktaları oluşturur ve günceller, bunları tanımladığınız şemalara ve onları düzenleyen klasörlere bağlar.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Uç noktaları JSON olarak listelemek başlı başına faydalıdır. Çıktıyı dallar arasında karşılaştırabilir veya her yolun beklediğiniz yanıtlara sahip olup olmadığını kontrol eden bir betiğe besleyebilirsiniz. İlgili uç noktaları folder komutuyla gruplayarak proje büyüdükçe gezinilebilir kalmasını sağlayın.
apidog security-scheme ile kimlik doğrulamayı tanımlayın
Kimlik doğrulama, sonradan eklenen bir özellik değil, sözleşmenin bir parçasıdır. security-scheme grubu, istemcilerin nasıl kimlik doğruladığını tanımlar: API anahtarları, taşıyıcı tokenlar, OAuth 2.0 vb. Bu, OpenAPI'deki components/securitySchemes ile eşleşir, böylece içe ve dışa aktarma sorunsuz bir şekilde gerçekleşir.
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Şemayı proje düzeyinde bir kez tanımlamak, her uç noktanın kendi kimlik doğrulamasını yeniden bildirmek yerine ona referans verebileceği anlamına gelir. Bu, bir linter'ın aksi takdirde size şikayet edeceği türden bir tutarlılıktır.
Yazımlarınızı apidog cli-schema validate ile doğrulayın
Değişiklikleri kaydetmeden veya bir projeyi CI'ye teslim etmeden önce, kaynak tanımlarınızın iyi biçimlendirilmiş olduğunu bilmek istersiniz. CLI, bir tanım dosyasını CLI'ın beklediği şemaya karşı kontrol eden bir cli-schema validate komutuyla birlikte gelir, böylece yanlış biçimlendirilmiş bir yazım sessizce kaydedilmek yerine hızla başarısız olur.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Bunu işlem hattınızda bir koruma adımı olarak çalıştırın: önce doğrulayın, sonra uygulayın. Sıfır olmayan bir çıkış, kötü bir kaynağın projeye ulaşmasını engellemek için işlem hattını durdurur. Bu, CLI yazımlarınızın doğrulanmasıdır, OpenAPI stil lint etmesi değildir; bunlar iki farklı iştir ve ikincisi için hala Spectral'ı istersiniz.
OpenAPI'ye geri aktarın
Apidog'da tasarlayın, ardından standart bir yapıtı araç zincirinizin geri kalanına teslim edin. apidog export, OpenAPI, HTML, Markdown veya Postman yazar.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Artık taşınabilir bir OpenAPI dosyasına geri döndünüz. Lint etme için Spectral'a, taslaklar için openapi-generator'a veya belge derlemenize besleyin. Entegre proje ve açık araç yığını birbirini dışlamaz; dışa aktarma aralarındaki köprüdür.
CI'ya entegre etme
Her iki yol da bir işlem hattında parlar çünkü her komutun bir çıkış kodu ve metin çıktısı vardır. Minimal bir tasarım kontrol işi, linter'ı çalıştırabilir, sonra doğrulama yapabilir, sonra demetleyebilir:
# stil ihlallerinde başarısız ol
spectral lint openapi.yaml
# uygulamadan önce herhangi bir CLI kaynak yazımını doğrula
apidog cli-schema validate --file resource.json
# sonraki adımlar için tek bir yapıta düzleştir
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Apidog'un çıktısı agentHints.nextSteps içeren JSON olduğundan, bu akış aynı zamanda bir yapay zeka kodlama aracısından da sorunsuz bir şekilde yönlendirilebilir. Aracı, yapılandırılmış sonucu okur, önerilen bir sonraki adımı görür ve çalıştırır, bir GUI'yi ekran kazımasına gerek kalmaz. Başlangıçta CLI'dan tasarım yapmanın tüm nedeni budur: bir insanın yazdığını, bir betik veya bir aracı da yazabilir.
Sık karşılaşılan sorunlar
Bölünmüş dosyalar alt araçları bozar. Birçok $ref dosyasına yayılmış bir tanım insanlar için harikadır ancak jeneratörler için gariptir. Kod üretmeden veya belge yayınlamadan önce her zaman tek bir dosyada demetleyin. Çözüm redocly bundle'dır.
Apidog'un lint edeceğini bekliyorsunuz. Etmez. Apidog kaynakları yönetir; bir stil rehberini uygulamaz veya OpenAPI kural ihlallerini işaretlemez. Bunun için Spectral veya vacuum'u döngüde tutun. apidog cli-schema validate'i bir linter olarak görmek yaygın bir karışıktır; bu, kaynak yapısını doğrular, OpenAPI stilini değil.
Düzenlemeden önce içe aktarmayı unutmak. Mevcut bir API'yi CLI aracılığıyla düzenliyorsanız, önce kaynak tanımını projeye içe aktarın. Boş bir projeyi düzenlemek ve eski uç noktalarınızın orada olmasını beklemek, kafanızın karışmasına yol açan hızlı bir yoldur.
Kimlik doğrulamanın bir kez yerine uç nokta başına tanımlanması. Proje düzeyinde bir security-scheme tanımlayın ve ona referans verin. Her işlemde kimlik doğrulamasını yeniden bildirmek, sözleşmelerin kaymasına neden olur.
Özetle
CLI'dan API tasarlamak, çok tıklama gerektiren bir görevi tekrarlanabilir komutlar setine dönüştürür. Açık yol, yani yazma, Spectral ile lint etme, Redocly ile demetleme, openapi-generator ile oluşturma, size tam kontrol ve kilitlenme olanağı sunmaz. Apidog CLI yolu size şemaların, uç noktaların ve kimlik doğrulamanın bir arada yaşadığı entegre bir proje sunar ve her komut aracıya hazır JSON döndürür. Dışa aktarma ikisi arasında köprü kurar, böylece asla takılı kalmazsınız.
Ekibinize uygun yolu seçin. Zaten Git'te tek amaçlı araç yığınıyla yaşıyorsanız, bunları koruyun ve taşınabilir bir yapıt istediğinizde apidog export'u ekleyin. Yapıştırmayı sürdürmek istemiyorsanız, Apidog'u İndirin, CLI'yı kurun ve bir fareye dokunmadan bir sonraki API'nizi tasarlayın.