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

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

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

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

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

คำว่าน้ำหนักเบาไม่ได้หมายถึงการมีประสิทธิภาพต่ำ แต่หมายถึงขนาดและการเสียดทาน มีสี่สิ่งที่เป็นตัวตัดสิน

ขนาดการติดตั้งและการพึ่งพา. ไบนารีเดียวหรือแพ็คเกจ npm เดียวดีกว่าเฟรมเวิร์ก หากการสร้างหน้าเอกสารหมายถึงการติดตั้งรันไทม์ภาษา, bundler, และระบบปลั๊กอิน นั่นไม่ใช่น้ำหนักเบา ไม่ว่าผลลัพธ์จะเป็นอย่างไร

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

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

ทำงานได้ทุกที่. ไม่มี GUI, ไม่ต้องเข้าสู่ระบบสำหรับเครื่องมือแบบเปิด, ไม่มีเซิร์ฟเวอร์ที่ต้องดูแลให้ทำงานอยู่เสมอ มันทำงานบนแล็ปท็อปของคุณและทำงานแบบเดียวกันในงาน CI สำหรับตัวเลือกที่ไม่มีค่าใช้จ่ายในวงกว้าง, รายการ เครื่องมือจัดทำเอกสาร API ฟรี มีแพลตฟอร์มต่างๆ; นี่คือส่วนของ CLI ในนั้น

ตอนนี้มาดูเครื่องมือกัน เริ่มจากตัวที่เล็กที่สุด

Widdershins

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

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

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

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

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

OpenAPI Generator เป็นที่รู้จักกันดีที่สุดสำหรับ client SDKs แต่มันก็มาพร้อมกับตัวสร้างเอกสารด้วย และมันมีประโยชน์เมื่อคุณมีแค่ข้อมูลจำเพาะ ตัวสร้าง `markdown` จะเขียนโฟลเดอร์ของ Markdown; ตัวสร้าง `html2` จะเขียนหน้า HTML แบบสแตนด์อโลนเดียว คุณสามารถใช้งานมันผ่าน npm wrapper โดยไม่ต้องติดตั้ง Java ด้วยตัวเอง

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/

npm wrapper ยังคงดาวน์โหลดไฟล์ JAR ที่ขับเคลื่อนโดย JDK อยู่เบื้องหลัง ดังนั้นมันจึงหนักกว่า Widdershins ในการรันครั้งแรก หลังจากนั้นมันก็เป็นการสร้างด้วยคำสั่งเดียว

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

Redocly CLI (build-docs)

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

npx @redocly/cli build-docs openapi.yaml

โดยค่าเริ่มต้นมันจะเขียน `redoc-static.html` เปลี่ยนชื่อด้วย `--output`:

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

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

Slate

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

# หลังจากโคลน repo ของ slate และติดตั้ง dependencies
bundle exec middleman build

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

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

Apidog CLI (export + doc)

เครื่องมือแบบเปิดข้างต้นแต่ละตัวครอบคลุมส่วนหนึ่ง: แปลง, เรนเดอร์, หรือโฮสต์ หาก API ของคุณมีอยู่ในโปรเจกต์อยู่แล้วแทนที่จะเป็นไฟล์ YAML เพียงไฟล์เดียว การนำมารวมกันเป็นเรื่องที่ยุ่งยาก นี่คือจุดที่ไบนารี `apidog-cli` เข้ามามีบทบาท มันคือส่วนเสริมแบบคอมมานด์ไลน์ของ Apidog และการส่งออกครั้งเดียวจะเปลี่ยนโปรเจกต์ให้เป็น Markdown หรือ HTML โดยไม่มี pipeline การสร้าง

ติดตั้งจาก npm และยืนยันตัวตนด้วยโทเค็น:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

จากนั้นส่งออกเอกสารของโปรเจกต์เป็น Markdown หรือ HTML ด้วยคำสั่งเดียว:

apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

CLI ยังจัดการทรัพยากรเอกสารโดยตรง `apidog doc` จัดการเอกสาร Markdown ของโปรเจกต์ และ `apidog docs-site` จัดการเว็บไซต์เอกสารที่เผยแพร่ ดังนั้นคุณสามารถแสดงรายการ, สร้าง, และอัปเดตเอกสารจากสคริปต์หรืองาน CI:

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

ผลลัพธ์เป็น JSON ที่มีโครงสร้าง ซึ่งทำให้ง่ายต่อการส่งต่อในขั้นตอนอื่น ๆ หรือส่งให้ตัวแทน สำหรับคำสั่งทั้งหมด, คู่มือฉบับสมบูรณ์ของ Apidog CLI จะอธิบายการยืนยันตัวตน, โปรเจกต์, และแต่ละกลุ่มคำสั่ง

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

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

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

สรุปสั้นๆ: หากคุณมีข้อมูลจำเพาะเปล่าๆ และต้องการ Markdown เพื่อ commit ให้ใช้ Widdershins หากคุณต้องการหน้า HTML ที่สามารถแชร์ได้ `redocly build-docs` คือวิธีที่เร็วที่สุด หากคุณกำลังเขียนเอกสารด้วยมือและต้องการเค้าโครงที่เหมาะสม ให้ใช้ Slate และหาก API ของคุณอยู่ในโปรเจกต์อยู่แล้ว และคุณต้องการการส่งออกพร้อมกับการจัดการเอกสารใน CLI เดียว ให้ใช้ Apidog สำหรับภาพรวมที่ไม่มีค่าใช้จ่ายโดยรวม, บทสรุป เครื่องมือจัดทำเอกสาร API ฟรี รวบรวมข้อมูลไว้ทั้งหมด

สรุป

เครื่องมือจัดทำเอกสารน้ำหนักเบาขึ้นอยู่กับกฎข้อเดียว: เลือกสิ่งที่เล็กที่สุดที่สร้างผลลัพธ์ที่คุณต้องการ Widdershins และ `redocly build-docs` ครอบคลุมกรณีส่วนใหญ่ของการแปลง spec เป็นเอกสารด้วยคำสั่งเดียว OpenAPI Generator คุ้มค่าเมื่อคุณกำลังสร้าง SDKs อยู่แล้ว Slate คุ้มค่ากับทรัพยากรที่ใช้มากขึ้นก็ต่อเมื่อคุณเขียนเอกสารด้วยมือเท่านั้น และเมื่อ API ของคุณอยู่ในโปรเจกต์จริงแทนที่จะเป็นไฟล์ที่กระจัดกระจาย, การส่งออกด้วย `apidog-cli` จะให้ Markdown หรือ HTML โดยไม่มี pipeline

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