Daha önce, Swagger 2.0'ı (OAS 2 olarak da bilinir) kullanıyor olabilirsiniz, ancak şimdi OpenAPI Specification (OAS) 3'e yükseltme zamanı. Bu makalede, yükseltme sürecinin temel noktalarını ve OAS 3 kullanarak API'leri belgelemenin esaslarını özetleyeceğiz.
Bu noktalardan bazıları, önceki OAS 2 (eski adıyla Swagger) belgeleri için hala geçerli olabilir, ancak daha önce tam olarak vurgulamamış olabileceğim için bunu belirtmekte fayda var.
Bu makaledeki kod örnekleri, GitHub'daki openapi.yaml dosyasında bulunan bookmarks.dev-api'nin OAS 3 spesifikasyonundan alınmıştır. Sonuçlar bookmarks.dev/api/docs/ adresinde görüntülenebilir.
İşte on önemli husus:
1. Spesifikasyon Belgesini Okuyun
OAS'nin en son sürümündeki önemli güncellemelerden bazılarını paylaşan ve OAS 2.0'dan OAS 3.0'a geçiş yaparken bilmeniz gerekenler hakkında ayrıntılı bilgiler sağlayan "OpenAPI 3.0'daki Yeniliklere Bir Rehber" makalesini okuyun. Bu makale, 1 saatlik "OpenAPI 3.0 ve Swagger'ın Geleceği İçin Anlamı" web seminerine dayanmaktadır.
2. Bir Dönüştürücü Web Hizmeti Kullanın
Swagger spesifikasyonlarınızı OpenAPI 3.0'a dönüştürmek için OpenAPI/Swagger 2.0'dan OpenAPI 3.0'a dönüştürücü web hizmetini kullanın.
https://converter.swagger.io/ adresinde çevrimiçi olarak mevcuttur ve ayrıca bir Docker görüntüsü olarak da kullanabilirsiniz:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. Spesifikasyonunuzu Doğrulayın ve Swagger Editor ile Önizleyin
Swagger Editor, YAML formatında Swagger API spesifikasyonlarını web tarayıcınızda düzenlemenizi ve anında belgelendirmeyi önizlemenizi sağlar.
Bunu çevrimiçi olarak veya npm yayınlanmış bir sürüm veya bir Docker görüntüsü olarak kullanabilirsiniz. Daha fazla ayrıntı için projenin README'sine bakın.
4. Belgelendirmelerinizi Swagger UI ile Sergileyin
Swagger UI, Swagger uyumlu API'ler için dinamik olarak güzel belgeler oluşturan bir HTML, JavaScript ve CSS kaynakları koleksiyonudur.
Benim gibi doğrudan, örneğin bookmarks.dev/api/docs/ gibi bir API rotası aracılığıyla Swagger UI belgelerine erişerek kullanabilirsiniz. İşte app.js'den bir kod parçacığı:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Açık spesifikasyon dosyasını (openapi.yaml) nodemon izlemenize (örneğin, nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) dahil etmek, ExpressJS sunucusunu manuel olarak yeniden başlatmadan UI'yi yeniden yüklemenize olanak tanıyarak yardımcı olabilir.
4.1. Code-First Yaklaşımı İçin swagger-jsdoc Kullanın
Dikkat çekici bir diğer nokta da, kodunuzdaki JSDoc açıklamaları aracılığıyla Swagger'ı entegre etmek için swagger-jsdoc kullanabilmenizdir. swagger-jsdoc projesi, mevcut, aktif, çalışan kodu, diğer Swagger araçlarına beslenebilecek bir spesifikasyon üreten ve ona "hayat veren" bir şekilde belgelemek istediğinizi varsayar, tersi değil.
Şu anda, belgeleri tek bir openapi.yaml dosyasında yönetiyorum, ancak gelecekte kullanmayı düşünebilirim.
5. Etiketleri Kullanarak İşlemleri Gruplandırın
Her API işlemine bir etiket listesi atayabilirsiniz, bu da Swagger UI ve Swagger Editor'ın işlemleri etiketlere göre görüntülemesini kolaylaştırır. Swagger UI'daki sıralamayı kontrol etmek için, bunları kök düzeyinde genel etiketler olarak eklemeniz gerekir. Ayrıca, oraya açıklamalar ve harici belgelere bağlantılar da ekleyebilirsiniz.
İşte API için kullandığım etiketler:
yamlCopy code
tags:- name: rootdescription: Kök uç noktaları işaretlemek için kullanılır- name: versiondescription: Proje sürümüne ve gitSha1'e erişin- name: public-bookmarksdescription: Genel yer işaretlerine erişin- name: personal-bookmarksdescription: Kişisel yer işaretleri üzerindeki işlemler- name: user-datadescription: Kullanıcı verileri üzerindeki işlemler- name: helperdescription: Yardımcı uç noktalar/işlemler
6. Sunucularla API Temel URL'lerini Belirtin
OpenAPI 3.0'da, API için bir veya daha fazla temel URL belirtmek için sunucular dizisini kullanırsınız. Sunucular, OpenAPI 2.0'da kullanılan host, basePath ve schemes anahtar kelimelerinin yerini alır. Her sunucunun bir URL'si ve isteğe bağlı olarak Markdown formatında bir açıklaması vardır.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Geliştirme için yerel sunucu- url: https://www.bookmarks.dev/apidescription: Ana (üretim) sunucusu
7. Bileşenlerle Kaynakları Tanımlayın ve Yeniden Kullanın
Genellikle, birkaç API işlemi ortak parametreleri paylaşır veya aynı yanıt yapısını döndürür. Kod tekrarını önlemek için, ortak tanımları genel bileşenler bölümüne yerleştirebilir ve bunları $ref kullanarak referans verebilirsiniz.
Örneğin, bir yer imleri listesinin göründüğü birkaç işlem için ortak olan yanıt için, components > responses altında bir BookmarkListResponse tanımlıyorum:
components:responses:BookmarkListResponse:description: Yer imleri listesicontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
Ve sonra, bunu get-public-bookmarks gibi farklı işlemlerde referans veriyorum:
yamlCopy code
/public/bookmarks:get:summary: Sorgu parametrelerini kullanarak genel yer imleri listesini döndürün.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
Yukarıda bahsedilen locationQueryParam'a dikkat edin. components > parameters altında tanımlanır ve yukarıda gösterilen örnek dahil olmak üzere API spesifikasyonunda birden fazla yerde referans verilir.
8. Netlik İçin Örnekler Ekleyin
Web hizmetinizin spesifikasyonunu daha net hale getirmek için parametrelere, özelliklere ve nesnelere örnekler ekleyebilirsiniz. Örnekler, API'niz için araçlar ve kitaplıklar tarafından okunabilir. Örneğin, bir mock API aracı, mock istekler oluşturmak için örnek değerler kullanabilir. Örnek veya örnek anahtarlarını kullanarak nesneler, tek tek özellikler ve işlem parametreleri için örnekler belirtebilirsiniz.
Örneğin, bir arama metni parametresi için örnekler olarak karmaşık değerlere sahip olabilirsiniz:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
Arama sorgusu (boşluklarla ayrılmış kelimeler). Mevcut özel filtreler:
* `lang:iso_language_code` - örneğin, İngilizce için `lang:en`, İspanyolca için `lang:es`, Almanca yer imleri için `lang:de`
* `site:site_URL` - örneğin, [www.codepedia.org](htt
