เครื่องมือ CLI ฟรี โอเพนซอร์ส สำหรับจัดทำเอกสาร API

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

รายการนี้คือส่วนที่เลือกมาจากเครื่องมือเอกสาร API แบบโอเพนซอร์สที่ทำงานจากบรรทัดคำสั่ง เครื่องมือทุกชิ้นในที่นี้เป็นซอร์สโค้ดที่สามารถเข้าถึงได้ภายใต้ลิขสิทธิ์ที่แท้จริง ไม่ว่าจะเป็น MIT หรือ Apache 2.0 โฮสต์อยู่บน GitHub และใช้งานได้ฟรีโดยไม่ต้องมีบัญชี คุณเพียงแค่ชี้ไปที่ไฟล์ OpenAPI หรือ Swagger แล้วมันจะให้ไฟล์ Markdown, หน้า HTML แบบสแตติก หรือเว็บไซต์เอกสารฉบับสมบูรณ์ที่คุณเป็นเจ้าของและโฮสต์เอง

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

มีข้อสังเกตอย่างตรงไปตรงมาในตอนแรก Apidog ปรากฏใกล้ท้าย และไม่ใช่เครื่องมือโอเพนซอร์ส แต่เป็นแพลตฟอร์ม freemium เชิงพาณิชย์ ฉันได้รวมไว้ที่นี่เพียงแค่เป็นส่วนเสริมที่มีป้ายกำกับสำหรับกรณีที่เครื่องมือโอเพนซอร์สมีข้อจำกัด และฉันจะระบุเส้นแบ่งนั้นอย่างชัดเจน

อะไรที่ทำให้เครื่องมือเอกสาร CLI เป็น “โอเพนซอร์ส”

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

ลิขสิทธิ์ที่แท้จริง MIT หรือ Apache 2.0 หมายความว่าคุณสามารถใช้งาน แก้ไข และเผยแพร่เครื่องมือเพื่อการค้าได้โดยไม่ต้องขออนุญาต ทั้งคู่ได้รับการรับรองจาก OSI Apache 2.0 เพิ่มการอนุญาตสิทธิบัตรที่ชัดเจน ซึ่งบางทีมกฎหมายอาจชอบ เครื่องมือทุกตัวด้านล่างมีลิขสิทธิ์หนึ่งในสองแบบนี้

เอาต์พุตที่สามารถโฮสต์ได้เอง จุดประสงค์ของเอกสารโอเพนคือไม่มีอะไรที่ขึ้นอยู่กับเซิร์ฟเวอร์ของผู้ขาย เครื่องมือเหล่านี้เขียนไฟล์สแตติก: Markdown ที่คุณคอมมิต, หน้า HTML เดียว หรือโฟลเดอร์ของ HTML/CSS/JS คุณสามารถโฮสต์บน GitHub Pages, S3 หรือเซิร์ฟเวอร์ Nginx ธรรมดา และมันจะยังคงทำงานได้ไม่ว่าโปรเจกต์ที่อยู่เบื้องหลังเครื่องมือจะยังคงอยู่หรือไม่ก็ตาม

การบำรุงรักษาและชุมชน ซอร์สโค้ดที่สามารถเข้าถึงได้จะมีประโยชน์ก็ต่อเมื่อโค้ดยังมีชีวิตอยู่ จำนวนดาว, การคอมมิตล่าสุด และปัญหาที่เปิดอยู่ (open issues) บอกคุณว่าการฟอร์ก (fork) จะทำได้หรือไม่หากคุณจำเป็นต้องทำ เครื่องมือบางตัวในที่นี้ถูกเก็บเข้าคลังแล้วแต่ยังคงใช้งานได้ ฉันจะบอกไว้

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

Redocly CLI

Redocly CLI เป็นวิธีที่เร็วที่สุดในการเปลี่ยนสเปคให้เป็นเอกสารอ้างอิง HTML ที่สมบูรณ์และครบถ้วนในตัวเอง มันเป็นลิขสิทธิ์ MIT และเป็นแบบ open core: CLI และเอนจิ้นการเรนเดอร์ Redoc ที่อยู่เบื้องหลังเป็นโอเพนซอร์สบน GitHub ในขณะที่ฟีเจอร์พอร์ทัลบางอย่างที่เป็นโฮสต์อยู่ในผลิตภัณฑ์แบบชำระเงินของ Redocly คำสั่ง build-docs อยู่ในส่วนโอเพนซอร์สทั้งหมด

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

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

ดีที่สุดสำหรับ: การสร้างเอกสารอ้างอิง API แบบหน้าเดียวที่สะอาดตาจากคำสั่งเดียว, ลิขสิทธิ์ MIT และโฮสต์เอง ข้อจำกัดอย่างตรงไปตรงมา: เอาต์พุตเป็นหน้าเดียว ดังนั้นจึงเป็นเอกสารอ้างอิงมากกว่าพอร์ทัลแบบหลายหน้า และการปรับแต่งธีมที่ซับซ้อนกว่านั้นอยู่ในระดับพรีเมียม หากคุณกำลังเปรียบเทียบเอนจิ้นการเรนเดอร์ต่างๆ กัน การเปรียบเทียบ Redocly alternatives จะแสดงให้เห็นว่าเส้นแบ่งโอเพนซอร์สอยู่ตรงไหน

Widdershins

Widdershins เป็นตัวแปลงบริสุทธิ์ภายใต้ลิขสิทธิ์ MIT มันอ่าน OpenAPI 3, Swagger 2 หรือ AsyncAPI และส่งออกเป็น Markdown นั่นคือหน้าที่ทั้งหมด เนื่องจากเอาต์พุตเป็น Markdown ธรรมดา คุณจึงเป็นเจ้าของมันได้อย่างสมบูรณ์: คอมมิต, เปรียบเทียบใน pull request หรือป้อนเข้าสู่เว็บไซต์สแตติกที่คุณใช้งานอยู่แล้ว

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

Markdown ที่มันเขียนเข้ากันได้กับ Slate ซึ่งทำให้มันจับคู่ได้อย่างลงตัวกับเครื่องมือสร้างเว็บไซต์แบบสแตติกที่อยู่ท้ายรายการนี้ แฟล็กที่มีประโยชน์: --omitHeader จะตัดส่วน front-matter ออก และ --language_tabs จะเลือกภาษาสำหรับตัวอย่างโค้ด

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

OpenAPI Generator

OpenAPI Generator มีลิขสิทธิ์ Apache 2.0 และดำเนินการโดยชุมชน แยกตัวจาก Swagger Codegen ในปี 2018 เป็นที่รู้จักกันดีที่สุดสำหรับ client SDKs แต่ก็มีเครื่องมือสร้างเอกสารด้วย: ตัวสร้าง markdown จะเขียนโฟลเดอร์ของ Markdown และ html2 จะเขียนหน้า HTML แบบสแตติกหนึ่งหน้า

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

ลิขสิทธิ์ Apache 2.0 และการอนุญาตสิทธิบัตรทำให้ง่ายต่อการอนุมัติสำหรับทีมกฎหมายที่ระมัดระวัง และโปรเจกต์นี้เป็นหนึ่งในโปรเจกต์ที่ได้รับการดูแลอย่างกระตือรือร้นที่สุดในพื้นที่นี้

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

Swagger Codegen

Swagger Codegen คือเครื่องมือสร้างที่ขับเคลื่อนด้วยเทมเพลตดั้งเดิมจากทีม Swagger ซึ่งได้รับอนุญาตภายใต้ Apache 2.0 มันเกิดขึ้นก่อนการแยกตัวของ OpenAPI Generator และยังคงได้รับการดูแลโดย SmartBear สำหรับเอกสาร มีสองเส้นทาง: html สำหรับเอกสารอ้างอิงหน้าเดียวแบบสแตติก และ dynamic-html สำหรับเว็บไซต์แบบอินเทอร์แอคทีฟขนาดเล็ก

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

ทั้งสองโปรเจกต์มี DNA และตัวเลือกมากมายร่วมกัน ดังนั้นหากทีมของคุณได้กำหนดมาตรฐานด้วยชุดเครื่องมือ Swagger แล้ว นี่จะช่วยให้คุณอยู่ภายในระบบเดียวกัน

ดีที่สุดสำหรับ: ทีมที่ลงทุนในระบบนิเวศของ Swagger อยู่แล้ว และต้องการเอกสารจากเครื่องมือ Apache 2.0 เดียวกันที่สร้าง stub ให้พวกเขา ข้อจำกัดอย่างตรงไปตรงมา: มันใช้ Java เป็นแบ็คเอนด์เหมือน OpenAPI Generator และการพัฒนาช้ากว่าการแยกตัวของชุมชน สำหรับการตั้งค่าใหม่ส่วนใหญ่ OpenAPI Generator เป็นตัวเลือกที่กระตือรือร้นกว่า Swagger Codegen ชนะในด้านความต่อเนื่อง

Docusaurus พร้อมปลั๊กอิน OpenAPI

หากหน้า HTML เดียวไม่เพียงพอและคุณต้องการเว็บไซต์เอกสารฉบับเต็มที่มีเวอร์ชัน Docusaurus คือหลักยึดที่เป็นโอเพนซอร์ส มันมีลิขสิทธิ์ MIT สร้างโดย Meta และเป็นหนึ่งในเครื่องมือสร้างเว็บไซต์สแตติกที่ใช้กันอย่างแพร่หลายที่สุดบนเว็บ ด้วยตัวมันเอง มันเรนเดอร์ Markdown และ MDX; ปลั๊กอิน docusaurus-openapi-docs ซึ่งเป็น MIT และได้รับการดูแลโดย Palo Alto Networks จะเพิ่มการสร้างเอกสารจากสเปค

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

หลังจากกำหนดค่าปลั๊กอินด้วยพาธสเปคของคุณแล้ว คำสั่ง gen-api-docs จะแปลงไฟล์ OpenAPI ให้เป็นหน้า MDX ที่เรนเดอร์ภายในเว็บไซต์ Docusaurus พร้อมแผง "ลองใช้" และแถบนำทางด้านข้าง

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

Slate

Slate คือรูปแบบเอกสาร API แบบสามคอลัมน์สุดคลาสสิก: การนำทางด้านซ้าย เนื้อหาตรงกลาง ตัวอย่างโค้ดด้านขวา ทั้งหมดนี้เรนเดอร์เป็นเว็บไซต์สแตติก มันมีลิขสิทธิ์ Apache 2.0 และขับเคลื่อนด้วย Middleman ดังนั้นจึงต้องการ Ruby toolchain แตกต่างจากตัวแปลงข้างต้น Slate ไม่อ่าน OpenAPI โดยตรง คุณเขียน Markdown แล้ว Slate จะเรนเดอร์มัน

# after cloning your Slate fork and running bundle install
bundle exec middleman build

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

ดีที่สุดสำหรับ: เอกสารที่จัดทำอย่างพิถีพิถัน มีการเล่าเรื่องที่คุณต้องการควบคุมโครงสร้างและเนื้อหาด้วยตนเอง บนเว็บไซต์สแตติกที่โฮสต์เองอย่างสมบูรณ์ ข้อจำกัดอย่างตรงไปตรงมา: รีโพสิทอรีดั้งเดิมถูกเก็บเข้าคลังแล้ว (ผู้ดูแลได้ถอยออกมา) แม้ว่ามันจะยังคงสร้างได้และการฟอร์กยังคงใช้งานอยู่ และการพึ่งพา Ruby นั้นหนักกว่าคำสั่ง npx บรรทัดเดียว หากเอกสารของคุณสร้างใหม่โดยตรงจากสเปค ตัวแปลงจะเบากว่า

Apidog CLI (ข้อสังเกตตรงไปตรงมา ไม่ใช่เครื่องมือโอเพนซอร์ส)

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

นั่นคือช่องว่างที่ไบนารี apidog-cli เข้ามาเติมเต็ม เพื่อให้ตรงไปตรงมาเกี่ยวกับลิขสิทธิ์: Apidog ไม่ใช่โอเพนซอร์ส มันเป็นแพลตฟอร์ม freemium เชิงพาณิชย์ที่มีระดับฟรี และ CLI สื่อสารกับโปรเจกต์ที่โฮสต์อยู่แทนที่จะเป็นสเปคในเครื่อง ฉันรวมมันไว้ที่นี่เพียงเพื่อให้การเปรียบเทียบมีความซื่อสัตย์ว่าเครื่องมือโอเพนซอร์สทำอะไรและไม่ครอบคลุมอะไร ไม่ใช่ในฐานะตัวเลือกโอเพนซอร์ส

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

การส่งออกเพียงครั้งเดียวจะเปลี่ยนโปรเจกต์ให้เป็น Markdown หรือ HTML โดยไม่มี build pipeline และ apidog doc กับ apidog docs-site จะจัดการทรัพยากรเอกสารจากสคริปต์ เอาต์พุตเป็น JSON ที่มีโครงสร้าง ดังนั้นจึงสามารถเชื่อมต่อกับ CI หรือ agent ได้อย่างราบรื่น คู่มือฉบับสมบูรณ์ของ Apidog CLI จะอธิบายการยืนยันตัวตนและกลุ่มคำสั่งแต่ละกลุ่ม หากเวิร์กโฟลว์การส่งออก Markdown คือสิ่งที่คุณต้องการ บทความ เครื่องมือสร้างเอกสาร API พร้อมการส่งออก Markdown จะลงลึกยิ่งขึ้น

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

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

จับคู่ลิขสิทธิ์และเอาต์พุตกับสิ่งที่ทีมของคุณต้องการเป็นเจ้าของ

สรุปสั้นๆ: สำหรับสเปคเปล่าและเอกสารอ้างอิง HTML ที่แชร์ได้ ให้ใช้ Redocly CLI สำหรับ Markdown ที่คุณควบคุมเวอร์ชัน ให้ใช้ Widdershins หากคุณกำลังสร้าง SDKs อยู่แล้ว OpenAPI Generator ก็สามารถสร้างเอกสารได้ด้วย และ Swagger Codegen ครอบคลุมคุณหากคุณใช้มาตรฐาน Swagger เมื่อคุณต้องการพอร์ทัลจริงที่มีการจัดการเวอร์ชันและคู่มือ Docusaurus บวกกับปลั๊กอิน OpenAPI คือหลักยึดโอเพนซอร์ส และ Slate คือตัวเลือกสำหรับเอกสารที่เขียนด้วยมือและควบคุมโดยบรรณาธิการ เครื่องมือทุกตัวที่กล่าวมาสามารถเข้าถึงซอร์สโค้ดได้และสามารถโฮสต์เองได้ ดังนั้นไม่มีสิ่งใดที่คุณเผยแพร่ขึ้นอยู่กับการที่ผู้ขายยังคงดำเนินธุรกิจอยู่ สำหรับมุมมองที่ไม่เสียค่าใช้จ่ายที่กว้างขึ้น สรุป เครื่องมือเอกสาร API ฟรี จะรวบรวมตัวเลือกโอเพนซอร์สและ freemium เข้าด้วยกัน

สรุป

การเลือก CLI เอกสารโอเพนซอร์สขึ้นอยู่กับลิขสิทธิ์ เอาต์พุต และที่อยู่ของเอกสารของคุณ ลิขสิทธิ์ MIT และ Apache 2.0 ทั้งคู่ช่วยให้คุณสามารถใช้งาน แก้ไข และโฮสต์เองได้โดยไม่มีค่าใช้จ่ายต่อผู้ใช้ ดังนั้นจงเลือกเครื่องมือที่เล็กที่สุดที่สร้างเอาต์พุตที่คุณต้องการ: Redocly CLI สำหรับหนึ่งหน้า, Widdershins สำหรับ Markdown, OpenAPI Generator หรือ Swagger Codegen สำหรับเอกสารข้าง SDKs ของคุณ, Docusaurus สำหรับพอร์ทัล, Slate สำหรับหน้าเว็บที่จัดทำด้วยตนเอง

หาก API ของคุณอยู่ในโปรเจกต์ที่มีการดูแลรักษา แทนที่จะเป็นไฟล์เดียวโดดๆ และคุณต้องการส่งออกเอกสารมากกว่าที่จะต้องเชื่อมต่อเครื่องมือสามตัว ดาวน์โหลด Apidog และลองใช้ apidog export กับโปรเจกต์ของคุณ มันสามารถใส่ในงาน CI ได้เพื่อให้เอกสารของคุณสร้างใหม่ทุกครั้งที่ API มีการเปลี่ยนแปลง เพียงแต่โปรดเข้าใจอย่างชัดเจนว่ามันเป็นแพลตฟอร์ม freemium ไม่ใช่ไบนารีโอเพนซอร์ส