สั้นๆ จบย่อหน้าเดียว ลูกพี่สั่ง ให้เขียนเอกสารประกอบ API โดยตอนแรก ลูกพี่ส่งตัว MkDocs และถามผมว่าจะใช้อะไรเขียน ผมบอกว่าใช้ Swagger ลองๆเขียนไปสักพัก ใช้ยากฉิบหาย สุดท้าย ผมเลือก Slate จบ


Photo by Samuel Zeller / Unsplash

รีวิวแบบยาวหน่อยๆ

บอกไว้ก่อน ทั้งหมดที่กำลังจะอ่านนี้ ผมเพิ่งลองใช้ได้ไม่นาน และไม่ได้อ่านเอกสารอย่างถ้วนถี่ๆๆๆๆ แฮ่กๆๆๆ

เริ่มเลย

ดาวบน GitHub

ชื่อ จำนวนดาว
MkDocs https://github.com/mkdocs/mkdocs/ 4,469
Swagger Editor https://github.com/swagger-api/swagger-editor 2,717
Slate https://github.com/lord/slate 20,022

Slate ชนะ ไสย์ๆ

ภาษาที่ใช้สร้าง

ชื่อ ภาษา
MkDocs Python
Swagger JavaScript/NodeJS
Slate Ruby

ข้อนี้ ผมชอบ Python, NodeJS ตามลำดับ ผมไม่ได้ลอง MkDocs เลยไม่รู้ว่ามันทำงานดีไหม ตัว Swagger Editor มันแก้แล้วเห็นแบบทันที ส่วน Slate แก้เสร็จแล้วต้องเซฟไฟล์และ Reload หน้าเว็บ ซึ่ง โหลดช้า Ruby เร็วส์... ส่วน Swagger Editor แม่งเซฟไฟล์หน้าเว็บไม่ได้ดาวน์โหลดได้อย่างเดียว งั้นให้ Slate ชนะไปแล้วกัน

ภาษา หรือ Syntax ที่ใช้เขียน Docฯ

ชื่อ ภาษา
MkDocs ยาแมว (YAML) ใช้สร้าง Layout, ใช้ Markdown เขียนเอกสาร
Swagger ใช้ยาแมว (YAML) เขียน (default) และ Import/Export JSON
Slate Markdown 1 ไฟล์ จบ

เห็น MkDocs แล้วกดปิดแทบไม่ทัน มันยุ่งไป ต้องสร้าง Layout เอง เขียนยาแมว แล้วก็เขียน Markdown ของแต่ละหน้าอีกที ส่วนตัว Swagger Editor มันมาเป็นยาแมว แล้วแม่ง ผมเขียนไม่เป็น กด tab ผิดฟ้อง error รัวๆเลย มาจบที่ Slate เขียน Markdown ไฟล์เดียวเลย หรือจะแยกไฟล์ก็ได้ Slate ชนะไปอีก 1 เม็ด

ฟีเจอร์เด็ดของแต่ละอัน

ชื่อ ฟีเจอร์
MkDocs ไม่ได้ลอง
Swagger gen client ได้, ลองรันโค้ดสร้าง request ผ่านหน้าเว็บได้เลย
Slate เขียนโค้ดตัวอย่าง ให้เลือกดูได้หลายๆภาษา

ฟีเจอร์ของ Swagger ดี ชนะตรงมันรันทดสอบได้เลย แต่ส่วนของ Slate ก็ดีตรงที่ มันเขียนโค้ดตัวอย่างให้เลือกได้ สรุป ด้วยความเอนเอียง Slate ชนะ

สรุป

ข้อดี

  • Swagger
    แก้ YAML หน้าเว็บและเห็นผลเลย รันทดสอบเรียกใช้ API ได้ผ่านหน้าเว็บ

  • Slate
    เขียนโค้ดตัวอย่างได้ เขียนเอกสารง่าย เพราะมันคือ Markdown

ข้อเสีย

  • Swagger
    ไม่ใช่ข้อเสียของ Swagger แต่ผมเขียน YAML ไม่เป็น
  • Slate
    แก้โค้ดเสร็จแล้ว ต้องโหลดหน้าเว็บใหม่ ซึ่งโหลดช้า ขนาดอยู่ที่ localhost น่ะ

จบท้าย ด้วยรูป

ผู้ชนะอันดับ 1 Slate

https://github.com/lord/slate

screenshot-slate

รองอันดับ 1 Swagger Editor

https://swagger.io/swagger-editor/

Swagger_Editor_Full-1

ที่โหล่

http://www.mkdocs.org/#overview

mkdocs-screenshot

a+rwx