DEV Community

Cover image for สุดยอดเครื่องมือ CLI น้ำหนักเบาสำหรับทำเอกสาร API
Thanawat Wongchai
Thanawat Wongchai

Posted on • Originally published at apidog.com

สุดยอดเครื่องมือ CLI น้ำหนักเบาสำหรับทำเอกสาร API

คุณมีไฟล์ OpenAPI และต้องการสร้างเอกสารจากไฟล์นั้นโดยไม่ต้องตั้งค่าบริการ เข้าสู่ระบบพอร์ทัล หรือเพิ่มขั้นตอน build ที่ดึง dependency จำนวนมาก คุณต้องการเพียงคำสั่งเดียวที่อ่านสเปกและสร้างไฟล์ Markdown หรือหน้า HTML เดี่ยวสำหรับโฮสต์ได้ทุกที่

ลองใช้ Apidog วันนี้

บทความนี้รวมเครื่องมือ CLI ที่เน้นขนาดเล็กและใช้งานตรงไปตรงมา: เป็นไบนารีเดียว, คำสั่ง npx บรรทัดเดียว, หรือแพ็กเกจที่ติดตั้งครั้งเดียวแล้วใช้ใน CI ได้ทันที บางตัวสร้าง Markdown เพื่อนำไปใช้กับเว็บไซต์เอกสารที่มีอยู่ บางตัวสร้าง HTML แบบสแตนด์อโลน

หากต้องการดูแพลตฟอร์มเอกสาร API ที่มี GUI เพิ่มเติม ดูบทสรุป เครื่องมือจัดทำเอกสาร REST API ยอดนิยม สำหรับรูปแบบและฟิลด์ที่เครื่องมือเหล่านี้อ่าน ให้ยึด OpenAPI Specification เป็นแหล่งอ้างอิงหลัก

อะไรที่ทำให้เครื่องมือ CLI “น้ำหนักเบา” สำหรับการจัดทำเอกสาร API

คำว่า “น้ำหนักเบา” ไม่ได้หมายถึงประสิทธิภาพต่ำ แต่หมายถึงลดขนาดการติดตั้งและลดขั้นตอนใน workflow โดยพิจารณาจาก 4 เรื่องต่อไปนี้

  1. ขนาดการติดตั้งและ dependency

    ไบนารีเดียวหรือแพ็กเกจ npm เดียวมักเหมาะกว่าเฟรมเวิร์กเต็มรูปแบบ หากต้องติดตั้ง language runtime, bundler และ plugin system เพียงเพื่อสร้างหน้าเอกสาร เครื่องมือนั้นไม่ใช่ตัวเลือกที่เบา

  2. เริ่มต้นได้เร็วและตั้งค่าน้อย

    เครื่องมือควรอ่าน openapi.yaml และสร้างผลลัพธ์ได้ทันที เช่น:

   tool openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

  1. มีหน้าที่เดียวชัดเจน

    รับ OpenAPI spec แล้วสร้างเอกสารเป็น Markdown หรือ HTML ผลลัพธ์ที่จำกัดขอบเขตช่วยให้คำสั่งคาดเดาได้ง่ายใน local environment และ CI

  2. รันได้ทุกที่

    ไม่ต้องใช้ GUI, ไม่ต้องดูแลเซิร์ฟเวอร์ และไม่ควรขึ้นกับขั้นตอน manual หลายจุด เครื่องมือควรทำงานเหมือนกันทั้งบนเครื่องนักพัฒนาและใน pipeline

หากกำลังมองหาตัวเลือกที่ไม่มีค่าใช้จ่ายในวงกว้าง ดู เครื่องมือจัดทำเอกสาร API ฟรี ได้เช่นกัน

Widdershins

Widdershins เป็นตัวเลือกที่เล็กที่สุดในรายการนี้ เป็นแพ็กเกจ npm เดียวสำหรับแปลง OpenAPI 3, Swagger 2 หรือ AsyncAPI เป็น Markdown โดยไม่เรนเดอร์เว็บไซต์และไม่เปิดเซิร์ฟเวอร์

ติดตั้งและสร้าง Markdown 

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

ผลลัพธ์คือไฟล์ api-docs.md ที่สามารถ commit เข้าสู่ repository, review ผ่าน diff และนำไปใช้กับ static site generator ได้

ตัวเลือกที่ใช้บ่อย 

# ตัด YAML front matter ออกจากผลลัพธ์
widdershins openapi.yaml -o api-docs.md --omitHeader

# ระบุภาษาใน code samples
widdershins openapi.yaml -o api-docs.md --language_tabs 'shell:Shell' 'javascript:JavaScript'
Enter fullscreen mode Exit fullscreen mode

Markdown ที่สร้างขึ้นเข้ากันได้กับ Slate จึงสามารถใช้ Widdershins เป็นขั้นตอนแปลง spec ก่อนส่งต่อไปยัง static documentation site ได้

เหมาะสำหรับ: แปลง spec เป็น Markdown อย่างรวดเร็วเพื่อ commit หรือใช้ในระบบเอกสารเดิม

ข้อจำกัด: ได้เฉพาะ Markdown ไม่มี UI แบบ interactive, ไม่มี “Try it” panel และไม่มีหน้าเว็บที่พร้อมโฮสต์ คุณต้องใช้ตัวเรนเดอร์หรือ static site generator เพิ่มเติมหากต้องการเว็บไซต์เอกสาร

OpenAPI Generator (ตัวสร้างเอกสาร)

OpenAPI Generator เป็นที่รู้จักจากการสร้าง client SDK แต่ยังมี generator สำหรับเอกสารด้วย:

  • markdown สร้างโฟลเดอร์ Markdown
  • html2 สร้างหน้า HTML แบบสแตนด์อโลน

ติดตั้งและใช้งาน 

npm install -g @openapitools/openapi-generator-cli

# สร้างเอกสาร Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# สร้างเอกสาร HTML
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

ตรวจสอบผลลัพธ์หลัง build:

find docs -maxdepth 2 -type f
find docs-html -maxdepth 2 -type f
Enter fullscreen mode Exit fullscreen mode

npm wrapper จะดาวน์โหลด JAR ที่ใช้ JDK อยู่เบื้องหลังในการรันครั้งแรก ดังนั้นจึงหนักกว่า Widdershins ช่วงเริ่มต้น แต่หลังจากนั้นสามารถเรียกผ่านคำสั่งเดิมใน CI ได้

เหมาะสำหรับ: โปรเจกต์ที่ใช้ OpenAPI Generator เพื่อสร้าง SDK อยู่แล้ว และต้องการสร้างเอกสารจาก spec เดียวกัน

ข้อจำกัด: ผลลัพธ์เป็น template-based และการรันครั้งแรกต้องดาวน์โหลด JAR จึงไม่ใช่ตัวเลือกแบบไบนารีเดี่ยวอย่างแท้จริง

Redocly CLI (build-docs)

หากต้องการหน้า HTML แบบสแตนด์อโลนที่พร้อมแชร์ด้วยคำสั่งเดียว Redocly CLI เป็นตัวเลือกที่ตรงที่สุด คำสั่ง build-docs จะ bundle OpenAPI spec เข้าเป็น HTML ไฟล์เดียวที่ใช้ Redoc

สร้างหน้าเอกสาร 

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

โดยค่าเริ่มต้น คำสั่งจะสร้างไฟล์ redoc-static.html

ระบุชื่อไฟล์ผลลัพธ์เองได้ด้วย --output:

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

จากนั้นเปิดไฟล์ใน browser หรือ deploy ไปยัง static host ได้ทันที:

open api.html
Enter fullscreen mode Exit fullscreen mode

เนื่องจากใช้ npx คุณจึงทดลองใช้งานได้โดยไม่ต้องติดตั้ง global package

เหมาะสำหรับ: สร้างหน้า API reference เดี่ยวที่ดูพร้อมใช้งานจาก OpenAPI spec

ข้อจำกัด: ผลลัพธ์เป็น HTML หน้าเดียว เหมาะกับ API reference มากกว่าพอร์ทัลเอกสารหลายหน้า การปรับธีมและตัวอย่างที่ละเอียดขึ้นอาจอยู่ในระดับชำระเงินของ Redocly

หากกำลังเปรียบเทียบตัวเรนเดอร์ประเภทเดียวกัน ดู ทางเลือก Redocly และ ทางเลือก Scalar

Slate

Slate แตกต่างจากเครื่องมืออื่นในรายการ เพราะไม่ได้แปลง OpenAPI spec เป็นเอกสารโดยตรง แต่เป็น static site generator สำหรับเอกสาร API ที่เขียนด้วย Markdown

Slate สร้าง layout แบบสามคอลัมน์:

  • navigation
  • เนื้อหาเอกสาร
  • code samples ด้านข้าง

Slate ใช้ Middleman จึงต้องมี Ruby และ Bundler

สร้างเว็บไซต์

หลัง clone repository ของ Slate และติดตั้ง dependencies แล้ว ให้รัน:

bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

ผลลัพธ์จะอยู่ในโฟลเดอร์ build/ ซึ่งสามารถ deploy ไปยัง static hosting ได้

ls build/
Enter fullscreen mode Exit fullscreen mode

ใช้ร่วมกับ Widdershins

Workflow ที่ใช้งานได้จริงคือ:

# 1. แปลง OpenAPI เป็น Markdown
widdershins openapi.yaml -o source/index.html.md

# 2. ให้ Slate build เว็บไซต์จาก Markdown
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

เหมาะสำหรับ: เอกสาร API ที่เขียนและดูแลด้วยมือ ต้องการควบคุมโครงสร้าง เนื้อหา และคำอธิบายเชิง narrative

ข้อจำกัด: เป็นตัวเลือกที่หนักที่สุด เพราะต้องใช้ Ruby tooling และไม่อ่าน OpenAPI โดยตรง หากเอกสารมาจาก spec และแทบไม่ต้องแก้ด้วยมือ ใช้ตัวแปลงหรือ HTML renderer จะเบากว่า

Apidog CLI (export + doc)

เครื่องมือแบบเปิดแต่ละตัวข้างต้นมักครอบคลุมเพียงบางส่วนของ workflow เช่น แปลง spec, เรนเดอร์ HTML หรือสร้าง static site แต่หาก API ของคุณถูกดูแลอยู่ในโปรเจกต์ Apidog อยู่แล้ว การเชื่อมหลายเครื่องมือเข้าด้วยกันอาจไม่จำเป็น

apidog-cli เป็น CLI สำหรับส่งออกโปรเจกต์เป็น Markdown หรือ HTML โดยไม่ต้องสร้าง pipeline แยกระหว่าง converter, renderer และ hosting

ติดตั้งและยืนยันตัวตน 

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

ส่งออกเอกสาร 

# ส่งออกเป็น Markdown
apidog export --project <projectId> --format markdown --output ./api-docs.md

# ส่งออกเป็น HTML
apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

ตรวจสอบว่าไฟล์ถูกสร้างแล้ว:

ls -lh ./api-docs.md ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

จัดการเอกสารผ่าน CLI

apidog doc ใช้จัดการเอกสาร Markdown ของโปรเจกต์ และ apidog docs-site ใช้จัดการเว็บไซต์เอกสารที่เผยแพร่แล้ว

# แสดงรายการเอกสารในโปรเจกต์
apidog doc list --project <projectId>

# แสดงรายการเว็บไซต์เอกสาร
apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

ผลลัพธ์เป็น JSON ที่มีโครงสร้าง จึงเหมาะสำหรับนำไปใช้ต่อใน script หรือ CI job

สำหรับรายการคำสั่งทั้งหมด ดู คู่มือฉบับสมบูรณ์ของ Apidog CLI

Apidog ไม่ใช่โอเพนซอร์สและไม่ใช่ไบนารีแบบ single-purpose โดย CLI จะสื่อสารกับโปรเจกต์ที่โฮสต์ไว้ นอกจากนี้ CLI ไม่ได้ทำหน้าที่ lint OpenAPI หรือบังคับ style guide ซึ่งเป็นส่วนที่ Redocly และ Spectral รองรับ

อย่างไรก็ตาม หากต้องการเส้นทางเดียวจาก API project ไปยัง Markdown หรือ HTML ที่แชร์ได้ apidog-cli ช่วยลดการต่อ pipeline หลายส่วนด้วยตนเองได้ สำหรับ workflow การส่งออก Markdown โดยเฉพาะ ดู ตัวสร้างเอกสาร API พร้อมการส่งออก Markdown

วิธีการเลือก

เลือกจากรูปแบบ input ที่มีอยู่และ output ที่ต้องการ:

เครื่องมือ ดีที่สุดสำหรับ การติดตั้ง โอเพนซอร์ส? ผลลัพธ์
Widdershins แปลง spec เป็น Markdown อย่างรวดเร็ว npm i -g widdershins ใช่ (MIT) Markdown
OpenAPI Generator สร้างเอกสารพร้อม SDKs npm i -g @openapitools/openapi-generator-cli ใช่ (Apache 2.0) Markdown หรือ HTML
Redocly CLI สร้าง HTML หน้าเดียวที่พร้อมแชร์ npx @redocly/cli ใช่ (MIT, open core) HTML แบบสแตนด์อโลน
Slate สร้างเว็บไซต์เอกสารที่คัดสรรด้วยมือ Ruby + Bundler ใช่ (Apache 2.0) เว็บไซต์สแตติก
Apidog CLI ส่งออกเอกสารจากโปรเจกต์ที่มีอยู่ npm i -g apidog-cli ไม่ (ฟรีเทียร์) Markdown หรือ HTML

สรุปการเลือกแบบเร็ว:

  • มี OpenAPI spec และต้องการ Markdown สำหรับ commit: ใช้ Widdershins
  • ต้องการ HTML หน้าเดียวที่เปิดหรือ deploy ได้ทันที: ใช้ Redocly CLI
  • สร้าง SDK อยู่แล้วและต้องการเอกสารจากเครื่องมือเดียวกัน: ใช้ OpenAPI Generator
  • ต้องการเขียนเอกสารแบบ narrative ด้วยมือ: ใช้ Slate
  • API อยู่ใน Apidog project และต้องการ export ผ่าน CLI: ใช้ Apidog CLI

สำหรับภาพรวมของเครื่องมือที่ไม่มีค่าใช้จ่าย ดู เครื่องมือจัดทำเอกสาร API ฟรี

สรุป

หลักการของเครื่องมือจัดทำเอกสารแบบน้ำหนักเบาคือ เลือกเครื่องมือที่เล็กที่สุดซึ่งสร้างผลลัพธ์ตามที่ต้องการ

  • Widdershins เหมาะกับการแปลง spec เป็น Markdown
  • redocly build-docs เหมาะกับการสร้าง HTML หน้าเดียว
  • OpenAPI Generator เหมาะเมื่อ workflow มีการสร้าง SDK อยู่แล้ว
  • Slate เหมาะกับเอกสารที่ต้องเขียนและควบคุมด้วยมือ
  • apidog-cli เหมาะกับการส่งออกเอกสารจาก API project ที่ดูแลอยู่แล้ว

หาก API ของคุณอยู่ในโปรเจกต์ Apidog ให้ ดาวน์โหลด Apidog แล้วลองรัน apidog export ใน CI เพื่อสร้างเอกสารใหม่ทุกครั้งที่ API เปลี่ยนแปลง

Top comments (0)