วิธีแปลง OpenAPI Specs เป็นเอกสาร Markdown ที่อ่านง่ายโดยอัตโนมัติ

ไฟล์ OpenAPI ของคุณคือแหล่งความจริงสำหรับ API ของคุณ มันแสดงรายการทุกเส้นทาง ทุกพารามิเตอร์ และทุกรูปแบบการตอบกลับ ปัญหาคือแทบไม่มีใครในทีมของคุณที่ต้องการอ่าน YAML หรือ JSON ดิบๆ วิศวกรแบ็กเอนด์ต้องการการอ้างอิงปลายทางอย่างรวดเร็วในรีโพสิทอรี นักพัฒนาฟรอนต์เอนด์ต้องการตารางฟิลด์คำขอที่พวกเขาสามารถตรวจสอบได้อย่างรวดเร็วในพูลรีเควสต์ นักเขียนด้านเทคนิคต้องการบางอย่างที่พวกเขาสามารถวางลงในวิกิได้โดยไม่ต้องพิมพ์โครงสร้างทั้งหมดใหม่

Markdown เป็นรูปแบบที่เหมาะสำหรับผู้อ่านทุกคน มันสามารถแสดงผลบน GitHub, ใน Confluence, ในตัวสร้างเว็บไซต์แบบคงที่ และในโปรแกรมแก้ไขข้อความธรรมดา ดังนั้นงานที่เกิดขึ้นซ้ำๆ ก็คือ: นำไฟล์ openapi.yaml ที่มีอยู่แล้ว และเปลี่ยนให้เป็น Markdown ที่สะอาดตาที่มนุษย์อ่านได้จริง การทำด้วยมือเป็นเรื่องช้าและจะคลาดเคลื่อนทันทีที่มีคนเพิ่มปลายทาง การทำโดยอัตโนมัติเป็นวิธีเดียวที่จะคงอยู่ได้เมื่อต้องเผชิญกับวงจรการเผยแพร่จริง

ทำไมต้องสร้าง Markdown จาก OpenAPI เลยด้วยซ้ำ

เอกสาร OpenAPI ถูกสร้างขึ้นสำหรับเครื่องมือ เครื่องมือต่างๆ จะแยกวิเคราะห์เพื่อสร้างไคลเอนต์ รันการทดสอบสัญญา ตรวจสอบคำขอ และแสดงผลเอกสารเชิงโต้ตอบ ความสามารถในการอ่านโดยเครื่องนั้นคือจุดประสงค์ทั้งหมด และคุ้มค่าที่จะปกป้อง หากคุณต้องการทบทวนเกี่ยวกับการรักษาสเปคให้ถูกต้อง คู่มือ เครื่องมือตรวจสอบ OpenAPI จะครอบคลุมการ lint ก่อนที่คุณจะสร้างอะไรจากมัน

Markdown แก้ปัญหาที่แตกต่างกัน: การเผยแพร่สู่มนุษย์ในสถานที่ที่ไม่รองรับการแสดงผล OpenAPI มีกรณีเฉพาะบางอย่างเกิดขึ้นซ้ำแล้วซ้ำอีก

• โฟลเดอร์ README.md หรือ /docs ในรีโพสิทอรี เพื่อให้ผู้ร่วมสร้างใหม่เห็นรายการปลายทางโดยไม่ต้องออกจากโค้ดเบส
• คำอธิบายพูลรีเควสต์ที่ต้องแสดงว่าปลายทางใหม่รองรับและส่งคืนอะไรบ้าง
• หน้า Confluence หรือ Notion ที่ทีมงานทั้งหมด รวมถึงผู้ที่ไม่ใช่วิศวกร สามารถตรวจสอบสัญญาได้
• เว็บไซต์เอกสารแบบคงที่ที่สร้างด้วย Docusaurus, MkDocs หรือ Hugo ซึ่งทั้งหมดนี้รับ Markdown เป็นอินพุต

คำสำคัญคือ 'โดยอัตโนมัติ' ไฟล์ Markdown ที่คุณเขียนครั้งเดียวแล้วลืมจะผิดพลาดภายในสปรินต์ถัดไป ไฟล์ Markdown ที่สร้างใหม่จากสเปคทุกครั้งที่มีการเปลี่ยนแปลงจะคงความถูกต้องตามสัญญาได้ฟรี นั่นคือความแตกต่างระหว่างเอกสารที่คนเชื่อถือกับเอกสารที่คนเรียนรู้ที่จะละเลย

วิธีการแปลง ตั้งแต่รวดเร็วไปจนถึงไร้ที่ติ

ไม่มีคำสั่งอย่างเป็นทางการเพียงคำสั่งเดียวที่มาพร้อมกับ OpenAPI เพื่อสร้าง Markdown แต่มีระบบนิเวศขนาดเล็กของเครื่องมือแปลงไฟล์และเอนจินเอกสารที่สร้างขึ้นในแพลตฟอร์ม API นี่คือภาพรวม โดยเรียงลำดับคร่าวๆ ตามปริมาณการตั้งค่าที่แต่ละวิธีต้องใช้

เลือกตามระดับการควบคุมที่คุณต้องการและปลายทางของผลลัพธ์ ส่วนถัดไปจะแสดงการทำงานของแต่ละวิธี

วิธีที่ 1: ตัวแปลงโอเพนซอร์สแบบบรรทัดเดียว

เส้นทางที่เร็วที่สุดคือการใช้ตัวแปลงโดยเฉพาะ มีสองตัวที่รู้จักกันดีซึ่งครอบคลุมโลกของ Node และ Python

สำหรับโปรเจกต์ Node, openapi-to-md จะรับเอกสาร v2 หรือ v3 ในรูปแบบ YAML หรือ JSON และเขียนไฟล์ Markdown ที่มีโครงสร้าง คุณสามารถรันได้โดยไม่ต้องติดตั้งแบบทั่วโลก:

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

สำหรับ Python toolchain, openapi-markdown ทำงานเดียวกันโดยการติดตั้ง pip และคำสั่งเดียว:

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

ทั้งสองวิธีจะอ่านสเปค ตรวจสอบทุกเส้นทางและ schema และส่งออกไฟล์ Markdown หนึ่งไฟล์พร้อมหัวข้อสำหรับแต่ละปลายทางและตารางสำหรับพารามิเตอร์และการตอบกลับ อาร์กิวเมนต์ไฟล์เอาต์พุตเป็นทางเลือกในเครื่องมือบางตัวเหล่านี้ หากไม่ระบุ ไฟล์จะใช้ชื่ออินพุตและเพิ่มนามสกุล .md นั่นก็เพียงพอสำหรับการอ้างอิงในรีโพสิทอรีที่คุณสร้างใหม่ได้ตามต้องการ

ข้อจำกัดของตัวแปลงที่รวดเร็วคือการควบคุมเค้าโครง คุณจะได้โครงสร้างของพวกเขา ไม่ใช่ของคุณ หากตารางเริ่มต้นของพวกเขาตรงกับวิธีที่ทีมของคุณอ่านเอกสาร คุณก็สามารถทำได้ในบรรทัดเดียว หากคุณต้องการตัวอย่างโค้ดในห้าภาษาหรือลำดับส่วนที่เฉพาะเจาะจง คุณจะต้องใช้วิธีถัดไป

วิธีที่ 2: Widdershins สำหรับเอกสารที่ปรับแต่งธีมได้พร้อมตัวอย่างโค้ด

Widdershins เป็นเครื่องมือ Node ที่ได้รับการยอมรับสำหรับการแปลงไฟล์ OpenAPI หรือ Swagger ให้เป็น Markdown ที่เข้ากันได้กับ Slate เป็นเครื่องมือที่คุณควรใช้เมื่อคุณต้องการแท็บโค้ดภาษาและเทมเพลตที่ปรับแต่งได้ และเมื่อ Markdown ถูกใช้เป็นอินพุตสำหรับตัวสร้างเว็บไซต์แบบคงที่ เช่น Docusaurus หรือ MkDocs

ติดตั้งและรันการแปลงพื้นฐาน:

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

เพิ่มภาษาสำหรับตัวอย่างโค้ดและลบส่วนหัว front-matter เมื่อคุณส่งเอาต์พุตไปยังที่ที่เพิ่มส่วนหัวของตัวเอง:

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

Widdershins ใช้ระบบเทมเพลต ดังนั้นคุณสามารถแทนที่เค้าโครงของส่วนใดก็ได้แทนที่จะยอมรับค่าเริ่มต้น นั่นทำให้มันเป็นสะพานเชื่อมระหว่างการสร้างแบบดิบๆ กับไซต์เอกสารที่สร้างขึ้นด้วยมืออย่างสมบูรณ์ ข้อเสียคือตอนนี้คุณต้องดูแลเทมเพลตและขั้นตอนการสร้าง ซึ่งเหมาะสำหรับรีโพสิทอรีเอกสารแต่เกินความจำเป็นสำหรับ README ด่วนๆ

วิธีที่ 3: สคริปต์ที่กำหนดเองเมื่อคุณต้องการเค้าโครงที่แน่นอน

บางครั้งเครื่องมือแปลงสำเร็จรูปก็ไม่สามารถสร้างรูปแบบที่คุณต้องการได้ อาจเป็นไปได้ว่าคุณต้องการไฟล์ Markdown หนึ่งไฟล์ต่อแท็ก หรือดัชนีปลายทางที่กะทัดรัด หรือตาราง schema ที่ตรงกับคู่มือสไตล์ภายใน ในกรณีนั้น ให้แยกวิเคราะห์สเปคด้วยตัวคุณเองแล้วสร้างเทมเพลตเอาต์พุต สเปคเป็นเพียงข้อมูลที่มีโครงสร้าง ดังนั้นจึงทำงานน้อยกว่าที่คิด

เวอร์ชัน Node แบบเรียบง่ายที่แสดงรายการทุกการดำเนินการมีลักษณะดังนี้:

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

นั่นคือโค้ดประมาณสี่สิบบรรทัดสำหรับการควบคุมเอาต์พุตทั้งหมด คุณตัดสินใจเลือกหัวข้อ คอลัมน์ตาราง การแบ่งไฟล์ ข้อเสียคือการบำรุงรักษา: เมื่อ OpenAPI เวอร์ชันที่คุณกำหนดเป้าหมายเพิ่มคุณสมบัติใหม่ สคริปต์ของคุณต้องเรียนรู้สิ่งนั้น สำหรับสไตล์ภายในที่เสถียร การแลกเปลี่ยนนี้มักจะคุ้มค่า สำหรับการครอบคลุมสเปคที่กว้างขวาง ให้พึ่งพาเครื่องมือแปลงที่ได้รับการดูแลแทน หากคุณกำลังชั่งน้ำหนักว่าจะเขียนสคริปต์นี้เองหรือซื้อ บทสรุปของ เครื่องมือสร้างเอกสาร API พร้อมการส่งออก Markdown เปรียบเทียบตัวเลือกที่ได้รับการดูแลแบบเคียงข้างกัน

วิธีที่ 4: เก็บรวบรวมสเปค, เอกสาร และการทดสอบไว้ด้วยกันใน Apidog

เครื่องมือแปลงข้างต้นทั้งหมดมีจุดบอดร่วมกันอย่างหนึ่ง พวกมันเปลี่ยนสเปคให้เป็น Markdown แล้วทั้งสองก็จะแยกออกจากกัน บางคนแก้ไข API ลืมรันตัวแปลงซ้ำ และ Markdown ก็จะแสดงข้อมูลที่ไม่ถูกต้อง วิธีแก้ไขคือหยุดมองว่าสเปคเป็นไฟล์ที่อยู่โดดเดี่ยว และเริ่มมองว่ามันเป็นส่วนหนึ่งของพื้นที่ทำงานที่เอกสารและการทดสอบจะอัปเดตไปพร้อมกับสเปคนั้น

นั่นคือโมเดลที่ Apidog ใช้ คุณนำเข้าไฟล์ openapi.yaml ที่มีอยู่ และ Apidog จะอ่านทุกเส้นทาง, schema และตัวอย่างลงในโปรเจกต์ จากนั้นคุณจะได้รับเอกสาร API ที่แสดงผลและโฮสต์ซึ่งสร้างโดยตรงจากสเปคที่นำเข้า โดยไม่มีขั้นตอนการสร้างแยกต่างหาก กระบวนการนำเข้าทั้งหมดครอบคลุมอยู่ใน วิธีนำเข้า Swagger หรือ OpenAPI และสร้างคำขอ และเส้นทางจากสเปคไปยังการอ้างอิงที่เผยแพร่ใน การสร้างเอกสาร API โดยอัตโนมัติจาก OpenAPI

มีสองสิ่งที่ทำให้วิธีนี้แตกต่างจากตัวแปลงแบบครั้งเดียวจบ

ประการแรก เอกสารรองรับบล็อกเนื้อหา Markdown ของคุณเอง ข้อมูลอ้างอิงปลายทางที่สร้างขึ้นมาจากสเปค และคุณสามารถเพิ่ม Markdown ที่เขียนด้วยมือรอบๆ มันได้: หน้าเริ่มต้นใช้งาน, บันทึกการรับรองความถูกต้อง, รายการบันทึกการเปลี่ยนแปลง เคล็ดลับในการสร้างเอกสารด้วย Apidog Markdown จะอธิบายถึงด้านการเขียนนั้น ดังนั้นคุณจึงไม่ต้องเลือกระหว่างเอกสารที่สร้างขึ้นกับเอกสารที่เขียนด้วยมือ คุณจะได้ทั้งสองอย่างในที่เดียว

ประการที่สอง สเปคที่นำเข้าเดียวกันนี้กลายเป็นพื้นฐานสำหรับสถานการณ์การทดสอบ คุณสร้างคำขอและการยืนยันเทียบกับปลายทางที่สเปคกำหนด จากนั้นรันการทดสอบเหล่านั้นเพื่อพิสูจน์ว่า API ที่ใช้งานจริงยังคงตรงกับสัญญาที่สร้างเอกสารของคุณ นั่นเป็นการปิดวงจรการคลาดเคลื่อน: หาก API เปลี่ยนแปลงและทำลายสัญญา การทดสอบจะล้มเหลว และคุณจะรู้ว่าเอกสารล้าสมัยก่อนที่ผู้อ่านจะรู้

หากต้องการทำตาม ให้ ดาวน์โหลด Apidog, นำเข้าสเปค และเปิดเอกสารที่สร้างขึ้นในโปรเจกต์เดียวกัน จุดประสงค์ไม่ใช่ว่า Apidog จะพิมพ์ไฟล์ .md ลงดิสก์ แต่มันคือการที่สเปค, เอกสารที่มนุษย์อ่านได้ และการทดสอบที่ทำให้ทั้งสองส่วนนี้เชื่อถือได้ ไม่ใช่สามไฟล์ที่แยกจากกันอีกต่อไป

ทำให้เป็นอัตโนมัติ: สร้าง Markdown ใหม่ใน CI

ตัวแปลงที่คุณรันด้วยมือคือตัวแปลงที่คุณจะลืมไป ค่าทั้งหมดของการสร้าง Markdown จาก OpenAPI จะปรากฏขึ้นก็ต่อเมื่อการสร้างทำงานด้วยตัวมันเอง ทุกครั้งที่มีการเปลี่ยนแปลง รูปแบบง่ายๆ คือ: ในแต่ละการพุชที่เกี่ยวข้องกับสเปค ให้สร้าง Markdown ใหม่แล้วคอมมิตกลับ หรือเผยแพร่

นี่คือ GitHub Actions job ที่จะสร้างข้อมูลอ้างอิงใหม่ทุกครั้งที่ไฟล์ openapi.yaml มีการเปลี่ยนแปลง:

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

ตอนนี้ Markdown จะไม่มีทางคลาดเคลื่อนไปจากสเปคเกินหนึ่งคอมมิต แนวคิดเดียวกันนี้ใช้ได้กับ GitLab CI หรือรันเนอร์ใดๆ ที่มี Node หรือ Python; เพียงแค่สลับขั้นตอนการแปลงเป็น widdershins หรือสคริปต์ของคุณ

ยังมีอีกหนึ่งส่วนที่ควรเชื่อมโยงเข้าไป เอกสารที่สร้างใหม่จะน่าเชื่อถือก็ต่อเมื่อสเปคที่ใช้สร้างยังคงถูกต้อง นั่นคือจุดที่การรันการทดสอบด้วยบรรทัดคำสั่งเข้ามามีบทบาทใน pipeline เดียวกัน Apidog CLI จะรันสถานการณ์การทดสอบที่คุณสร้างขึ้นกับสเปคที่นำเข้าของคุณ โดยไม่ใช้ UI ด้วยคำสั่งเดียว:

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

มันจะออกจากโปรแกรมด้วยค่าที่ไม่ใช่ศูนย์หากมีการยืนยันใดๆ ล้มเหลว ซึ่งจะทำให้การสร้างล้มเหลว ซึ่งจะหยุดคุณจากการเผยแพร่เอกสารที่อธิบาย API ที่ไม่ทำงานเช่นนั้นอีกต่อไป รายละเอียดแฟล็กทั้งหมดอยู่ใน เอกสารอ้างอิงคำสั่ง apidog run และการตั้งค่า pipeline ที่กว้างขึ้นอยู่ใน คู่มือฉบับสมบูรณ์ของ Apidog CLI จับคู่การสร้างเอกสารกับการทดสอบสัญญา แล้วทั้งสองจะเสริมซึ่งกันและกัน: สเปคสร้างเอกสาร และการทดสอบพิสูจน์สเปค

การปรับปรุง Markdown ที่สร้างขึ้น

Markdown ที่สร้างขึ้นมักจะไม่สมบูรณ์แบบในการลองครั้งแรก นิสัยบางอย่างช่วยให้มันอ่านง่ายขึ้น

• ลบส่วนหัว (front matter) ที่สร้างขึ้นโดยอัตโนมัติเมื่อตัวเรนเดอร์เป้าหมายไม่ต้องการ Widdershins ทำสิ่งนี้ด้วย --omitHeader; สำหรับเครื่องมืออื่นๆ การใช้ sed อย่างรวดเร็วบนส่วนบนสุดของไฟล์ก็ใช้ได้
• ตัดสินใจว่าจะแบ่งไฟล์อย่างไร ไฟล์ Markdown ขนาดใหญ่ไฟล์เดียวก็ใช้ได้สำหรับ README สำหรับไซต์เอกสาร ให้แบ่งตามแท็กหรือทรัพยากรเพื่อให้แต่ละหน้าสั้นลง
• ใช้ตัวอย่างที่สมจริง ตัวแปลงส่วนใหญ่ดึงค่าตัวอย่างโดยตรงจากสเปค ดังนั้นคุณภาพของเอกสารที่สร้างขึ้นจะขึ้นอยู่กับคุณภาพของ examples ใน OpenAPI ยิ่งตัวอย่างดีเท่าไร เอกสารที่ได้ก็จะยิ่งดีขึ้นเท่านั้น
• สร้างใหม่ อย่าแก้ไขด้วยมือ ทันทีที่คุณแก้ไข Markdown ที่สร้างขึ้นด้วยมือ การแปลงครั้งถัดไปจะเขียนทับการเปลี่ยนแปลงของคุณ วางเนื้อหาที่เขียนด้วยมือในไฟล์แยกต่างหาก และปล่อยให้ตัวสร้างดูแลเฉพาะส่วนอ้างอิงเท่านั้น

หากสเปคของคุณรก ให้แก้ไขที่แหล่งกำเนิด สเปคที่สะอาดขึ้นจะสร้างเอกสารที่สะอาดขึ้น และโพสต์ เครื่องมือตรวจสอบ OpenAPI แสดงวิธีการ lint สำหรับช่องว่างที่ทำให้เกิดผลลัพธ์ที่ไม่น่าดู

การเลือกวิธีที่เหมาะสมสำหรับทีมของคุณ

เลือกเครื่องมือให้ตรงกับปลายทางของ Markdown และระดับการควบคุมที่คุณต้องการ

• คุณต้องการการอ้างอิงในรีโพสิทอรีด้วยคำสั่งเดียวและไม่จุกจิกเรื่องเค้าโครง: ใช้ openapi-to-md หรือ openapi-markdown
• คุณกำลังสร้างไซต์เอกสารพร้อมตัวอย่างโค้ดและต้องการเทมเพลตที่ปรับแต่งธีมได้: ใช้ Widdershins
• คุณมีคู่มือสไตล์ภายในที่ตัวแปลงไม่สามารถจับคู่ได้: เขียนสคริปต์ขนาดเล็กบนสเปคที่แยกวิเคราะห์
• คุณต้องการเอกสาร, สเปค และการทดสอบที่ทำให้พวกมันถูกต้องอยู่ในพื้นที่ทำงานเดียวกัน พร้อมเอาต์พุตที่โฮสต์และไม่มีการสร้างแยกต่างหากให้ต้องดูแล: นำเข้าสเปคเข้าสู่ Apidog

สิ่งเหล่านี้ไม่ได้แยกขาดจากกัน ทีมจำนวนมากใช้ Apidog เป็นแหล่งความจริงสำหรับสเปคและเอกสารที่โฮสต์ จากนั้นรันตัวแปลงใน CI เพื่อวางข้อมูลอ้างอิง Markdown ลงในรีโพสิทอรีสำหรับการอ่านแบบออฟไลน์ สเปคยังคงเป็นต้นฉบับ; Markdown เป็นสิ่งประดิษฐ์ที่ได้มาซึ่งคุณสามารถสร้างใหม่ได้ทุกเมื่อ

สรุป

การแปลง OpenAPI เป็น Markdown เป็นปัญหาที่แก้ไขได้แล้ว ตราบใดที่คุณถือว่าสเปคเป็นแหล่งที่มาและ Markdown เป็นไฟล์ที่ได้มา สำหรับการอ้างอิงรีโพสิทอรีที่รวดเร็ว ตัวแปลงแบบบรรทัดเดียว เช่น openapi-to-md ก็ทำงานได้ สำหรับไซต์เอกสารที่ปรับแต่งธีมได้ Widdershins ให้เทมเพลตและแท็บโค้ด สำหรับเค้าโครงภายในที่แน่นอน สคริปต์สั้นๆ บนสเปคที่แยกวิเคราะห์ก็มีชัย และเมื่อคุณต้องการให้สเปค เอกสารที่แสดงผล และการทดสอบที่ทำให้พวกมันซิงค์กันอยู่ร่วมกัน การนำเข้าสู่ Apidog จะช่วยขจัดความคลาดเคลื่อนที่ทำให้วิธีการอื่นๆ เสียหายเมื่อเวลาผ่านไป

ไม่ว่าคุณจะเลือกอะไร ให้ทำมันโดยอัตโนมัติ สร้าง Markdown ใน CI ทุกครั้งที่มีการเปลี่ยนแปลงสเปค แล้วเอกสารที่ทีมของคุณอ่านจะตรงกับ API ที่พวกเขาอธิบายเสมอ