จากบทความเรื่อง
รวม Tips & Tricksในการสร้าง Swagger UI ให้กับ Gin REST API ด้วย Swaggo
อธิบายถึงการสร้าง API Documentation
โดยทำการสร้างมาจาก Code Annotation ในส่วนของ comment
ด้วย command swag
ซึ่งเป็นแนวทางหนึ่งในการสร้างเอกสารขึ้นมา
แต่ก็ยังไม่แนวทางอื่น ๆ ใช้งานเช่นกัน
ยกตัวอย่างเช่น
การเขียน API Specification ในรูปแบบของ
Swagger 3 หรือ Open API specification ก่อน
ทั้งในรูปแบบ XML, JSON และ YAML เป็นต้น
จากนั้นทำการ generate source code ของ REST API หรือ Web Services ขึ้นมา
ให้แบบอัตโนมัติผ่านเครื่องมือที่สนับสนุน Swagger
แต่ต้องดูด้วยว่าสนับสนุน Swagger version ไหนบ้างด้วย (2 หรือ 3)
ตัวอย่างของเครื่องมือ เช่น
- Swagger codegen สำหรับการ generate code ในภาษาหลัก ๆ ทั้ง C#, Java, Go, JavaScript และ Python เป็นต้น
- Go swagger สำหรับการ generate code ในภาษา Go
- OpenAPI Codegen สำหรับ Swagger version 3 ขึ้นไป และได้ภาษา Go ออกมา (เลือกได้ด้วยทั้ง HTTP/Echo และ Gin)
- Swag สำหรับ Swagger version 2 ได้ออกมาเป็นภาษา Go
- สาย GRPC ก็มีเช่น GRPC Gateway
ในรูปแบบนี้ควรจะทำการออกแบบ API อยู่ในรูปแบบ Swagger ไปเลย
ไม่ต้องไปออกแบบใน Spreadsheet
มิเช่นนั้นมันจะเกิดความซ้ำซ้อนขึ้นมาโดยใช่เหตุ
แต่ code ที่ได้มานั้น หลาย ๆ คนอาจจะไม่ชอบ
เลยทำให้ไปเลือกใช้วิธีแรกคือ เขียน code
เพื่อสร้าง API Specification/documentation ออกมา
แสดงแนวทางทั้งสองดังรูป
ลองเลือกดูว่าแบบไหนที่เหมาะสมกับการทำงานของเรา
หลังจากที่เราได้ API Specification ออกมาแล้ว
มันสามารถนำไปใช้งานหรือประโยชน์ได้อีกเพียบ
แสดงดังรูป
สุดท้ายแล้ว เรานำเครื่องมือเหล่านี้มาเพื่อให้เกิดประโยชน์หรือไม่
หรือมันมาทำให้เราช้าลงหรือเป็นภาระมากยิ่งขึ้น
ดังนั้นต้องมาวางแผนและตกลงการใช้งานร่วมกันด้วยเสมอนะครับ