OpenAPI dosyanız, API'nizin temel doğruluk kaynağıdır. Her yolu, her parametreyi, her yanıt şeklini listeler. Sorun şu ki, ekibinizdeki neredeyse hiç kimse ham YAML veya JSON okumak istemiyor. Bir arka uç mühendisi depoda hızlı bir uç nokta referansı ister. Bir ön uç geliştiricisi, bir çekme isteğinde tarayabileceği bir istek alanları tablosu ister. Bir teknik yazar, tüm şemayı yeniden yazmadan bir wiki'ye yapıştırabileceği bir şey ister.
Markdown, tüm bu okuyuculara uygun formattır. GitHub'da, Confluence'da, statik site oluşturucuda ve düz metin düzenleyicide işlenir. Dolayısıyla yinelenen görev şudur: zaten var olan bir openapi.yaml dosyasını alın ve insanların gerçekten açtığı temiz Markdown'a dönüştürün. Elle yapmak yavaştır ve birisi bir uç nokta eklediği anda sapar. Otomatik yapmak, gerçek bir yayın döngüsüyle temasta hayatta kalan tek versiyondur.
düğme
Neden OpenAPI'den Markdown Üretmeli?
Bir OpenAPI belgesi makineler için oluşturulmuştur. Araçlar, istemciler oluşturmak, sözleşme testleri yapmak, istekleri doğrulamak ve etkileşimli belgeler sunmak için onu ayrıştırır. Bu makine tarafından okunabilirlik asıl noktadır ve korunmaya değerdir. Şartnamenin kendisini doğru tutma konusunda bir hatırlatıcı isterseniz, OpenAPI doğrulayıcı araçları kılavuzu, ondan herhangi bir şey üretmeden önce lint yapmayı kapsar.
Markdown farklı bir sorunu çözer: OpenAPI oluşturucu çalıştırmayan yerlerde insanlara dağıtım. Birkaç somut durum tekrar tekrar ortaya çıkıyor.
- Depoda bir
README.mdveya/docsklasörü, böylece yeni bir katkıda bulunan kişi kod tabanından ayrılmadan uç nokta listesini görür. - Yeni bir uç noktanın neyi kabul ettiğini ve neyi döndürdüğünü göstermesi gereken bir çekme isteği açıklaması.
- Mühendis olmayanlar da dahil olmak üzere daha geniş ekibin sözleşmeyi gözden geçirdiği bir Confluence veya Notion sayfası.
- Docusaurus, MkDocs veya Hugo ile oluşturulmuş, hepsi Markdown'ı girdi olarak kabul eden bir statik belge sitesi.
Anahtar kelime otomatiktir. Bir kez yazıp unuttuğunuz bir Markdown dosyası, bir sonraki sprint'e kadar yanlış olur. Her değişiklikle şartnameden yeniden oluşturulan bir Markdown dosyası, sözleşmeye ücretsiz olarak sadık kalır. İnsanların güvendiği belgeler ile insanların görmezden gelmeyi öğrendiği belgeler arasındaki fark budur.
Dönüştürme yöntemleri: hızlıdan eksiksize
OpenAPI ile birlikte gelen Markdown üretmek için tek bir resmi komut yoktur. Bunun yerine, küçük bir dönüştürücü ekosistemi ve API platformlarına yerleşik belge motorları vardır. İşte her birinin yaklaşık ne kadar kurulum gerektirdiğine göre sıralanmış görünüm.
| Yöntem | En İyisi İçin | Elde Ettiğiniz Çıktı |
|---|---|---|
openapi-to-md / openapi-markdown |
Hızlı, yapılandırmasız bir Markdown dökümü | Tek bir Markdown dosyası veya şema tabloları |
| Widdershins | Kod sekmeleri içeren Slate/Docusaurus tarzı belgeler | Dil örnekleriyle temalanabilir Markdown |
| Ayrıştırılmış şartname üzerinde özel bir betik | Ekibinizin tam olarak istediği düzen | Ne şablonlarsanız |
| Apidog | Tek bir çalışma alanında şartname içe aktarma, işlenmiş belgeler ve testler | Barındırılan belgeler artı Markdown içerik blokları |
Ne kadar kontrol ihtiyacınız olduğuna ve çıktının nerede olması gerektiğine göre seçin. Sonraki bölümlerde her biri çalışırken gösterilecektir.
Yöntem 1: Tek satırlık açık kaynaklı bir dönüştürücü
En hızlı yol özel bir dönüştürücüdür. İki iyi bilineni Node ve Python dünyalarını kapsar.
Bir Node projesi için, openapi-to-md YAML veya JSON formatında bir v2 veya v3 belgesini alır ve yapılandırılmış bir Markdown dosyası yazar. Küresel kurulum olmadan çalıştırabilirsiniz:
npx openapi-to-md openapi.yaml api-reference.md
Bir Python araç zinciri için, openapi-markdown aynı işi bir pip kurulumu ve tek bir komutla yapar:
pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md
Her ikisi de şartnameyi okur, her yolu ve şemayı gezer ve uç nokta başına başlıklar ile parametreler ve yanıtlar için tablolar içeren tek bir Markdown dosyası çıkarır. Bu araçların bazılarında çıktı dosyası argümanı isteğe bağlıdır; onu atlarsanız, girdi adını .md uzantısıyla varsayılan olarak kullanırlar. Bu, isteğe bağlı olarak yeniden oluşturduğunuz bir depo referansı için yeterlidir.
Hızlı dönüştürücülerdeki ödünleşim, düzen kontrolüdür. Sizin değil, onların yapısını alırsınız. Varsayılan tabloları ekibinizin belgeleri okuma şekliyle eşleşiyorsa, tek bir satırda işiniz biter. Beş dilde kod örneklerine veya belirli bir bölüm sırasına ihtiyacınız varsa, bir sonraki yöntemi istersiniz.
Yöntem 2: Kod örnekleriyle temalanabilir belgeler için Widdershins
Widdershins, bir OpenAPI veya Swagger dosyasını Slate uyumlu Markdown'a dönüştürmek için kurulmuş Node aracıdır. Dil kodu sekmeleri ve özelleştirilebilir bir şablon istediğinizde ve Markdown, Docusaurus veya MkDocs gibi bir statik site oluşturucuyu beslediğinde başvurmanız gereken araçtır.
Kurun ve temel dönüştürmeyi çalıştırın:
npm install -g widdershins
widdershins openapi.yaml -o api-reference.md
Kod örnekleri dilleri ekleyin ve çıktıyı kendi eklediği bir yere aktarırken ön-madde başlığını çıkarın:
widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
--omitHeader openapi.yaml -o api-reference.md
Widdershins bir şablon sistemi kullanır, bu nedenle varsayılanı kabul etmek yerine herhangi bir bölümün düzenini geçersiz kılabilirsiniz. Bu, ham bir döküm ile tamamen el yapımı bir belge sitesi arasında bir köprü oluşturur. Maliyeti ise artık bir şablona ve bir derleme adımına sahip olmanızdır ki bu, bir belge deposu için uygun, ancak hızlı bir README için abartılıdır.
Yöntem 3: Tam bir düzene ihtiyacınız olduğunda özel bir betik
Bazen hazır dönüştürücülerin hiçbiri istediğiniz şekli üretmez. Belki etiket başına bir Markdown dosyasına, kompakt bir uç nokta dizinine veya dahili bir stil kılavuzuna uyan şema tablolarına ihtiyacınız vardır. Bu durumda, şartnameyi kendiniz ayrıştırın ve çıktıyı şablonlayın. Şartname sadece yapılandırılmış veridir, bu yüzden göründüğünden daha az iş demektir.
Her işlemi listeleyen minimal bir Node sürümü şöyle görünür:
import { readFileSync, writeFileSync } from "node:fs";
import yaml from "js-yaml";
const spec = yaml.load(readFileSync("openapi.yaml", "utf8"));
const lines = [`# ${spec.info.title}`, "", spec.info.description ?? "", ""];
for (const [path, methods] of Object.entries(spec.paths)) {
for (const [method, op] of Object.entries(methods)) {
lines.push(`## ${method.toUpperCase()} ${path}`);
lines.push("");
lines.push(op.summary ?? "");
lines.push("");
const params = op.parameters ?? [];
if (params.length) {
lines.push("| Name | In | Required | Description |");
lines.push("| ---- | -- | -------- | ----------- |");
for (const p of params) {
lines.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |`);
}
lines.push("");
}
}
}
writeFileSync("api-reference.md", lines.join("\n"));
Bu, çıktı üzerinde tam kontrol sağlayan yaklaşık kırk satırdır. Başlıkları, tablo sütunlarını, dosya bölmesini siz belirlersiniz. Dezavantajı bakımdır: hedeflediğiniz OpenAPI sürümü bir özellik eklediğinde, betiğinizin bunu öğrenmesi gerekir. Stabil bir dahili stil için, bu takas genellikle değerlidir. Geniş şartname kapsamı için bunun yerine bakımı yapılan bir dönüştürücüye güvenin. Bunu betiklemeyi mi yoksa satın almayı mı düşündüğünüzü tartıyorsanız, Markdown dışa aktarımı olan API belge oluşturucularının derlemesi, bakımı yapılan seçenekleri yan yana karşılaştırır.
Yöntem 4: Şartnameyi, belgeleri ve testleri Apidog'da bir arada tutun
Yukarıdaki dönüştürücülerin hepsinin ortak bir kör noktası vardır. Bir şartnameyi Markdown'a dönüştürürler ve sonra ikisi birbirinden ayrılır. Birisi API'yi düzenler, dönüştürücüyü yeniden çalıştırmayı unutur ve Markdown yalan söyler. Çözüm, şartnameyi tek başına yaşayan bir dosya olarak görmeyi bırakıp, belgelerin ve testlerin onunla birlikte güncellendiği bir çalışma alanının parçası olarak görmeye başlamaktır.
Apidog'un kullandığı model budur. Mevcut openapi.yaml dosyanızı içe aktarırsınız ve Apidog her yolu, şemayı ve örneği bir projeye okur. Buradan, içe aktarılan şartnameden doğrudan oluşturulmuş, barındırılan API belgeleri elde edersiniz, ayrı bir derleme adımına gerek kalmaz. Tam içe aktarma akışı Swagger veya OpenAPI nasıl içe aktarılır ve istekler nasıl oluşturulur makalesinde, şartnameden yayınlanmış referansa giden yol ise OpenAPI'den otomatik API belge oluşturma makalesinde açıklanmıştır.
İki şey bunu tek seferlik bir dönüştürücüden farklı kılar.
- Birincisi, belgeler kendi Markdown içerik bloklarınızı destekler. Oluşturulan uç nokta referansı şartnameden gelir ve siz onun etrafına elle yazılmış Markdown'ı katmanlaştırırsınız: bir başlangıç sayfası, kimlik doğrulama notları, değişiklik günlüğü girişleri. Apidog Markdown ile belge oluşturma ipuçları, bu yazım tarafını ele alır. Yani oluşturulan ve yazılan belgeler arasında seçim yapmıyorsunuz; her ikisini de tek bir yerde elde ediyorsunuz.
- İkincisi, aynı içe aktarılan şartname test senaryolarının temelini oluşturur. Şartnamenin tanımladığı uç noktalara karşı istekler ve iddialar oluşturur, sonra bunları canlı API'nin belgelerinizi üreten sözleşmeyle hala eşleştiğini kanıtlamak için çalıştırırsınız. Bu, sapma döngüsünü kapatır: API değişir ve sözleşmeyi bozarsa, testler başarısız olur ve bir okuyucu fark etmeden önce belgelerin güncelliğini yitirdiğini bilirsiniz.
Takip etmek için, Apidog'u indirin, bir şartnameyi içe aktarın ve oluşturulan belgeleri aynı projede açın. Önemli olan, Apidog'un diske bir .md dosyası yazdırması değildir. Önemli olan, şartnamenin, insan tarafından okunabilir belgelerin ve her ikisini de doğru tutan testlerin artık birbirinden ayrı üç dosya olmamasıdır.
Otomatikleştirin: CI'da Markdown'ı yeniden oluşturun
Elle çalıştırdığınız bir dönüştürücü, unuttuğunuz bir dönüştürücüdür. OpenAPI'den Markdown oluşturmanın tüm değeri, yalnızca oluşturma her değişiklikte kendi kendine çalıştığında ortaya çıkar. Desen basittir: şartnameyi etkileyen her gönderimde, Markdown'ı yeniden oluşturun ve geri kaydedin veya yayınlayın.
İşte openapi.yaml değiştiğinde referansı yeniden oluşturan bir GitHub Actions işi:
name: Generate API docs
on:
push:
paths:
- "openapi.yaml"
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- name: Convert spec to Markdown
run: npx openapi-to-md openapi.yaml docs/api-reference.md
- name: Commit regenerated docs
run: |
git config user.name "docs-bot"
git config user.email "docs-bot@users.noreply.github.com"
git add docs/api-reference.md
git diff --staged --quiet || git commit -m "docs: regenerate API reference"
git push
Artık Markdown, şartnameden asla bir commit'ten fazla sapamaz. Aynı fikir GitLab CI'da veya Node veya Python ile çalışan herhangi bir yürütücüde de çalışır; dönüştürme adımını widdershins veya kendi betiğinizle değiştirin.
Dahil etmeye değer bir parça daha var. Yeniden oluşturulan belgeler, yalnızca geldikleri şartname hala doğruysa güvenilirdir. İşte burada bir komut satırı test çalıştırması aynı ardışık düzende yerini alır. Apidog CLI, içe aktardığınız şartnameye karşı oluşturduğunuz test senaryolarını tek bir komutla, başsız bir şekilde çalıştırır:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Herhangi bir iddia başarısız olursa sıfır olmayan bir kodla çıkar, bu da derlemeyi başarısız kılar ve artık o şekilde davranmayan bir API'yi tanımlayan belgeleri yayınlamanızı engeller. Tüm bayrak yüzeyi apidog run komut referansında ve daha geniş ardışık düzen kurulumu Apidog CLI tam kılavuzunda yer almaktadır. Belge oluşturmayı bir sözleşme testiyle eşleştirin ve ikisi birbirini güçlendirir: şartname belgeleri üretir ve test şartnameyi kanıtlar.
Oluşturulan Markdown'ı Temizleme
Oluşturulan Markdown ilk denemede nadiren mükemmeldir. Birkaç alışkanlık onu okunabilir kılar.
- Hedef oluşturucu istemediğinde otomatik olarak oluşturulan ön içeriği kaldırın. Widdershins bunu
--omitHeaderile yapar; diğer araçlar için dosyanın üst kısmında hızlı birsedişe yarar. - Bir dosya bölme işlemine karar verin. Tek bir dev Markdown dosyası bir README için iyidir. Bir belge sitesi için, her sayfa kısa olsun diye etikete veya kaynağa göre bölün.
- Örnekleri gerçek tutun. Çoğu dönüştürücü örnek değerlerini doğrudan şartnameden çeker, bu nedenle oluşturulan belgelerinizin kalitesi, OpenAPI'deki
exampleskalitenizi takip eder. Daha iyi örnekler girer, daha iyi belgeler çıkar. - Yeniden oluşturun, elle düzenlemeyin. Oluşturulan Markdown'ı elle düzenlediğiniz anda, bir sonraki dönüştürme sizi üzerine yazar. Elle yazılmış içeriği ayrı dosyalara koyun ve oluşturucunun yalnızca referans bölümüne sahip olmasına izin verin.
Şartnamenizin kendisi dağınıksa, kaynağında düzeltin. Daha temiz şartnameler daha temiz belgeler oluşturur ve OpenAPI doğrulayıcı araçları gönderisi, çirkin çıktı üreten boşlukları nasıl lint edeceğinizi gösterir.
Ekibiniz İçin Doğru Yöntemi Seçmek
Aracı, Markdown'ın nereye gitmesi gerektiğine ve ne kadar kontrole ihtiyacınız olduğuna göre eşleştirin.
- Tek bir komutla bir depo referansı istiyorsunuz ve düzen konusunda seçici değilsiniz:
openapi-to-mdveyaopenapi-markdownkullanın. - Kod örnekleri içeren bir belge sitesi oluşturuyorsunuz ve temalanabilir bir şablon istiyorsunuz: Widdershins kullanın.
- Dönüştürücülerin eşleşemeyeceği dahili bir stil kılavuzunuz var: ayrıştırılmış şartname üzerinde küçük bir betik yazın.
- Belgelerin, şartnamenin ve onları doğru tutan testlerin tek bir çalışma alanında, barındırılan çıktı ile ve ayrı bir derleme adımına gerek kalmadan birlikte yaşamasını istiyorsunuz: şartnameyi Apidog'a aktarın.
Bunlar birbirini dışlamaz. Birçok ekip, şartname ve barındırılan belgeler için Apidog'u doğruluk kaynağı olarak kullanır, ardından çevrimdışı okuma için depoya bir Markdown referansı bırakmak üzere CI'da bir dönüştürücü çalıştırır. Şartname kanonik kalır; Markdown ise istediğiniz zaman yeniden oluşturabileceğiniz türetilmiş bir yapıdır.
Özet
OpenAPI'yi Markdown'a dönüştürmek, şartnameyi kaynak ve Markdown'ı türetilmiş bir dosya olarak gördüğünüz sürece çözülmüş bir sorundur. Hızlı bir depo referansı için, openapi-to-md gibi tek satırlık bir dönüştürücü işi görür. Temalanabilir bir belge sitesi için Widdershins size şablonlar ve kod sekmeleri sunar. Tam bir dahili düzen için, ayrıştırılmış şartname üzerinde kısa bir betik kazanır. Ve şartnamenin, işlenmiş belgelerin ve onları senkronize tutan testlerin birlikte yaşamasını istediğinizde, Apidog'a aktarmak, zamanla diğer her yaklaşımı bozan sapmayı ortadan kaldırır.
Ne seçerseniz seçin, otomatikleştirin. Her şartname değişikliğinde CI'da Markdown'ı oluşturun ve ekibinizin okuduğu belgeler her zaman tanımladıkları API ile eşleşecektir.
düğme