Cara Mengonversi Spesifikasi OpenAPI ke Dokumentasi Markdown Bersih Otomatis

File OpenAPI Anda adalah sumber kebenaran untuk API Anda. File ini mencantumkan setiap jalur, setiap parameter, setiap bentuk respons. Masalahnya adalah hampir tidak ada seorang pun di tim Anda yang ingin membaca YAML atau JSON mentah. Seorang insinyur backend menginginkan referensi endpoint cepat di repositori. Seorang pengembang frontend menginginkan tabel bidang permintaan yang dapat mereka pindai dalam permintaan tarik (pull request). Seorang penulis teknis menginginkan sesuatu yang dapat mereka tempel ke wiki tanpa harus mengetik ulang seluruh skema.

Markdown adalah format yang cocok untuk semua pembaca tersebut. Format ini dirender di GitHub, di Confluence, di generator situs statis, dan di editor teks biasa. Jadi, tugas berulang adalah ini: ambil file openapi.yaml yang sudah ada, dan ubah menjadi Markdown bersih yang benar-benar dibuka oleh manusia. Melakukannya secara manual lambat dan akan menyimpang saat seseorang menambahkan endpoint. Melakukannya secara otomatis adalah satu-satunya versi yang bertahan dalam siklus rilis yang nyata.

Mengapa perlu menghasilkan Markdown dari OpenAPI?

Sebuah dokumen OpenAPI dibuat untuk mesin. Alat memparsialnya untuk menghasilkan klien, menjalankan tes kontrak, memvalidasi permintaan, dan merender dokumen interaktif. Keterbacaan oleh mesin adalah intinya, dan layak untuk dilindungi. Jika Anda ingin menyegarkan kembali pengetahuan tentang menjaga spesifikasi tetap benar, panduan alat validator OpenAPI membahas pemeriksaan (linting) sebelum Anda menghasilkan apa pun darinya.

Markdown memecahkan masalah yang berbeda: distribusi kepada manusia di tempat-tempat yang tidak menjalankan perender OpenAPI. Beberapa kasus konkret muncul berulang kali.

• Folder README.md atau /docs di repositori, sehingga kontributor baru melihat daftar endpoint tanpa meninggalkan codebase.
• Deskripsi permintaan tarik (pull-request) yang perlu menunjukkan apa yang diterima dan dikembalikan oleh endpoint baru.
• Halaman Confluence atau Notion di mana tim yang lebih luas, termasuk non-insinyur, meninjau kontrak.
• Situs dokumentasi statis yang dibangun dengan Docusaurus, MkDocs, atau Hugo, yang semuanya menerima Markdown sebagai input.

Kata kuncinya adalah otomatis. File Markdown yang Anda tulis sekali dan lupakan akan menjadi salah pada sprint berikutnya. File Markdown yang dihasilkan ulang dari spesifikasi pada setiap perubahan akan tetap sesuai dengan kontrak secara gratis. Itulah perbedaan antara dokumen yang dipercaya orang dan dokumen yang orang pelajari untuk diabaikan.

Metode konversi, dari yang cepat hingga anti-gagal

Tidak ada perintah resmi tunggal yang disertakan dengan OpenAPI untuk menghasilkan Markdown. Sebaliknya, ada ekosistem kecil konverter ditambah mesin dokumen yang terintegrasi dalam platform API. Berikut adalah gambaran umumnya, diurutkan kira-kira berdasarkan seberapa banyak penyiapan yang dibutuhkan masing-masing.

Pilih berdasarkan seberapa banyak kontrol yang Anda butuhkan dan di mana output harus ditempatkan. Bagian selanjutnya menunjukkan setiap metode berjalan.

Metode 1: konverter open-source satu baris

Jalur tercepat adalah konverter khusus. Dua yang terkenal mencakup dunia Node dan Python.

Untuk proyek Node, openapi-to-md mengambil dokumen v2 atau v3 dalam format YAML atau JSON dan menulis file Markdown terstruktur. Anda dapat menjalankannya tanpa instalasi global:

npx openapi-to-md openapi.yaml api-reference.md

Untuk toolchain Python, openapi-markdown melakukan pekerjaan yang sama dengan instalasi pip dan satu perintah:

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md

Keduanya membaca spesifikasi, menelusuri setiap jalur dan skema, dan mengeluarkan satu file Markdown dengan judul per endpoint dan tabel untuk parameter dan respons. Argumen file output bersifat opsional di beberapa alat ini; biarkan kosong dan mereka akan menggunakan nama input dengan ekstensi .md secara default. Itu cukup untuk referensi repositori yang Anda hasilkan ulang sesuai permintaan.

Kelemahan konverter cepat adalah kontrol tata letak. Anda mendapatkan struktur mereka, bukan milik Anda. Jika tabel default mereka sesuai dengan cara tim Anda membaca dokumen, Anda selesai dalam satu baris. Jika Anda membutuhkan contoh kode dalam lima bahasa atau urutan bagian tertentu, Anda menginginkan metode berikutnya.

Metode 2: Widdershins untuk dokumen yang dapat diubah tema dengan contoh kode

Widdershins adalah alat Node yang sudah mapan untuk mengubah file OpenAPI atau Swagger menjadi Markdown yang kompatibel dengan Slate. Ini adalah pilihan yang tepat ketika Anda menginginkan tab kode bahasa dan template yang dapat disesuaikan, serta ketika Markdown menjadi input bagi generator situs statis seperti Docusaurus atau MkDocs.

Instal dan jalankan konversi dasar:

npm install -g widdershins
widdershins openapi.yaml -o api-reference.md

Tambahkan bahasa contoh kode dan hilangkan header front-matter ketika Anda mengalirkan output ke tempat yang menambahkan header sendiri:

widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
  --omitHeader openapi.yaml -o api-reference.md

Widdershins menggunakan sistem template, sehingga Anda dapat menimpa tata letak bagian mana pun alih-alih menerima yang default. Ini menjadikannya jembatan antara dump mentah dan situs dokumen yang sepenuhnya dibuat secara manual. Biayanya adalah Anda sekarang memiliki template dan langkah pembangunan, yang bagus untuk repo dokumentasi dan berlebihan untuk README cepat.

Metode 3: skrip kustom saat Anda membutuhkan tata letak yang tepat

Terkadang tidak ada konverter siap pakai yang menghasilkan bentuk yang Anda inginkan. Mungkin Anda membutuhkan satu file Markdown per tag, atau indeks endpoint yang ringkas, atau tabel skema yang sesuai dengan panduan gaya internal. Dalam kasus tersebut, parse spesifikasi sendiri dan buat template outputnya. Spesifikasi hanyalah data terstruktur, jadi ini lebih mudah daripada kedengarannya.

Versi Node minimal yang mencantumkan setiap operasi terlihat seperti ini:

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"));

Itu sekitar empat puluh baris untuk kontrol penuh atas output. Anda memutuskan judul, kolom tabel, pemisahan file. Kekurangannya adalah pemeliharaan: ketika versi OpenAPI yang Anda targetkan menambahkan fitur, skrip Anda harus mempelajarinya. Untuk gaya internal yang stabil, pertukaran itu biasanya sepadan. Untuk cakupan spesifikasi yang luas, bersandarlah pada konverter yang terpelihara sebagai gantinya. Jika Anda menimbang apakah akan membuat skrip ini atau membelinya, rangkuman generator dokumentasi API dengan ekspor Markdown membandingkan opsi-opsi yang terpelihara secara berdampingan.

Metode 4: menjaga spesifikasi, dokumen, dan pengujian tetap bersama di Apidog

Semua konverter di atas memiliki satu titik buta. Mereka mengubah spesifikasi menjadi Markdown, dan kemudian keduanya menyimpang. Seseorang mengedit API, lupa menjalankan ulang konverter, dan Markdown menjadi tidak akurat. Solusinya adalah berhenti memperlakukan spesifikasi sebagai file yang berdiri sendiri dan mulai memperlakukannya sebagai bagian dari ruang kerja tempat dokumen dan pengujian diperbarui bersamanya.

Itulah model yang digunakan Apidog. Anda mengimpor openapi.yaml yang sudah ada, dan Apidog membaca setiap jalur, skema, dan contoh ke dalam sebuah proyek. Dari sana Anda mendapatkan dokumentasi API yang dirender dan di-host yang dihasilkan langsung dari spesifikasi yang diimpor, tanpa langkah pembangunan terpisah. Alur impor lengkap dibahas dalam cara mengimpor Swagger atau OpenAPI dan menghasilkan permintaan, dan jalur dari spesifikasi ke referensi yang diterbitkan dalam pembuatan dokumentasi API otomatis dari OpenAPI.

Dua hal yang membuat ini berbeda dari konverter sekali jalan.

• Pertama, dokumentasi mendukung blok konten Markdown Anda sendiri. Referensi endpoint yang dihasilkan berasal dari spesifikasi, dan Anda menempatkan Markdown yang ditulis tangan di sekitarnya: halaman memulai, catatan otentikasi, entri catatan perubahan. Tips untuk membuat dokumentasi dengan Apidog Markdown menjelaskan sisi penulisan tersebut. Jadi, Anda tidak memilih antara dokumen yang dihasilkan dan yang ditulis; Anda mendapatkan keduanya di satu tempat.
• Kedua, spesifikasi yang diimpor yang sama menjadi dasar untuk skenario pengujian. Anda membangun permintaan dan penegasan terhadap endpoint yang ditentukan spesifikasi, lalu menjalankannya untuk membuktikan bahwa API langsung masih sesuai dengan kontrak yang menghasilkan dokumen Anda. Ini menutup lingkaran penyimpangan: jika API berubah dan melanggar kontrak, pengujian gagal, dan Anda tahu dokumen tersebut kedaluwarsa sebelum pembaca mengetahuinya.

Untuk mengikuti, unduh Apidog, impor spesifikasi, dan buka dokumen yang dihasilkan di proyek yang sama. Intinya bukan bahwa Apidog mencetak file .md ke disk. Intinya adalah bahwa spesifikasi, dokumen yang mudah dibaca manusia, dan pengujian yang menjaga keduanya tetap jujur tidak lagi menjadi tiga file yang terputus.

Jadikan otomatis: hasilkan ulang Markdown di CI

Konverter yang Anda jalankan secara manual adalah konverter yang akan Anda lupakan. Nilai penuh dari menghasilkan Markdown dari OpenAPI hanya terlihat ketika generasi berjalan dengan sendirinya, pada setiap perubahan. Polanya sederhana: pada setiap push yang menyentuh spesifikasi, hasilkan ulang Markdown dan commit kembali, atau publikasikan.

Berikut adalah pekerjaan GitHub Actions yang menghasilkan ulang referensi setiap kali openapi.yaml berubah:

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

Sekarang Markdown tidak akan pernah menyimpang lebih dari satu commit dari spesifikasi. Ide yang sama berlaku di GitLab CI atau runner mana pun dengan Node atau Python; ganti langkah konversi dengan widdershins atau skrip Anda.

Ada satu lagi bagian yang patut diintegrasikan. Dokumen yang dihasilkan ulang hanya dapat dipercaya jika spesifikasi asalnya masih akurat. Di sinilah eksekusi pengujian baris perintah mendapatkan tempatnya di pipeline yang sama. Apidog CLI menjalankan skenario pengujian yang Anda buat terhadap spesifikasi yang diimpor, tanpa kepala (headless), dengan satu perintah:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Ini akan keluar dengan nilai non-nol jika ada penegasan yang gagal, yang menyebabkan pembangunan gagal, yang menghentikan Anda menerbitkan dokumen yang menjelaskan API yang tidak lagi berperilaku seperti itu. Permukaan bendera lengkap ada di referensi perintah apidog run, dan pengaturan pipeline yang lebih luas di panduan lengkap Apidog CLI. Pasangkan pembuatan dokumen dengan pengujian kontrak dan keduanya saling memperkuat: spesifikasi menghasilkan dokumen, dan pengujian membuktikan spesifikasi.

Membersihkan Markdown yang dihasilkan

Markdown yang dihasilkan jarang sempurna pada percobaan pertama. Beberapa kebiasaan membuatnya tetap mudah dibaca.

• Hapus front matter yang dibuat secara otomatis jika perender target tidak menginginkannya. Widdershins melakukannya dengan --omitHeader; untuk alat lain, sed cepat di bagian atas file berfungsi.
• Putuskan pembagian file. Satu file Markdown raksasa baik-baik saja untuk README. Untuk situs dokumen, pisahkan berdasarkan tag atau sumber daya agar setiap halaman pendek.
• Jaga agar contoh tetap realistis. Sebagian besar konverter mengambil nilai contoh langsung dari spesifikasi, sehingga kualitas dokumen yang Anda hasilkan mengikuti kualitas examples Anda di OpenAPI. Contoh yang lebih baik masuk, dokumen yang lebih baik keluar.
• Hasilkan ulang, jangan edit secara manual. Saat Anda mengedit Markdown yang dihasilkan secara manual, konversi berikutnya akan menimpa Anda. Letakkan konten yang ditulis tangan dalam file terpisah dan biarkan generator hanya memiliki bagian referensi.

Jika spesifikasi Anda sendiri berantakan, perbaiki pada sumbernya. Spesifikasi yang lebih bersih menghasilkan dokumen yang lebih bersih, dan postingan alat validator OpenAPI menunjukkan cara memeriksa celah yang menghasilkan output yang buruk.

Memilih metode yang tepat untuk tim Anda

Sesuaikan alat dengan tujuan Markdown dan seberapa banyak kontrol yang Anda butuhkan.

• Anda menginginkan referensi repo dalam satu perintah dan tidak rewel tentang tata letak: gunakan openapi-to-md atau openapi-markdown.
• Anda membangun situs dokumen dengan contoh kode dan menginginkan template yang dapat diubah temanya: gunakan Widdershins.
• Anda memiliki panduan gaya internal yang tidak dapat dicocokkan oleh konverter: tulis skrip kecil di atas spesifikasi yang di-parse.
• Anda menginginkan dokumen, spesifikasi, dan pengujian yang menjaga keduanya tetap akurat dalam satu ruang kerja, dengan output yang di-hosting dan tanpa pembangunan terpisah untuk diawasi: impor spesifikasi ke Apidog.

Ini tidak saling eksklusif. Banyak tim menggunakan Apidog sebagai sumber kebenaran untuk spesifikasi dan dokumen yang di-host-nya, kemudian menjalankan konverter di CI untuk menempatkan referensi Markdown ke dalam repositori untuk dibaca secara offline. Spesifikasi tetap kanonik; Markdown adalah artefak turunan yang dapat Anda hasilkan ulang kapan saja.

Kesimpulan

Mengonversi OpenAPI ke Markdown adalah masalah yang sudah terpecahkan selama Anda memperlakukan spesifikasi sebagai sumber dan Markdown sebagai file turunan. Untuk referensi repo yang cepat, konverter satu baris seperti openapi-to-md sudah cukup. Untuk situs dokumen yang dapat diubah tema, Widdershins memberi Anda template dan tab kode. Untuk tata letak internal yang tepat, skrip singkat di atas spesifikasi yang di-parse adalah pemenangnya. Dan ketika Anda ingin spesifikasi, dokumen yang dirender, dan pengujian yang menjaga keduanya tetap sinkron untuk hidup bersama, mengimpor ke Apidog menghilangkan penyimpangan yang merusak setiap pendekatan lain seiring waktu.

Apa pun yang Anda pilih, otomatiskan. Hasilkan Markdown di CI pada setiap perubahan spesifikasi, dan dokumen yang dibaca tim Anda akan selalu sesuai dengan API yang mereka jelaskan.