ปัญหาและคำถามหนึ่งที่น่าสนใจ สำหรับการพัฒนาระบบ API คือถ้าระบบงานของเราไม่มี API Document เช่น Swager หรือ OpenAPI และ Scalarเราจะสร้างขึ้นมาอย่างไรดีแถม code ก็ไม่สามารถแก้ไขอะไรได้อีก (ทั้งไม่มีสิทธิ์ และ code เก่ามาก ๆ)ดังนั้นมาดูแนวทางการแก้ไขกันหน่อย
ระบบงานต่าง ๆ นั้น ยิ่งนานไประบบยิ่งมีส่วนการทำงานต่าง ๆ เยอะขึ้น ซับซ้อนมากขึ้นทั้ง product, domain, service และ messaging ต่าง ๆ ดังนั้นเราจะจัดการสิ่งต่าง ๆ เหล่านี้อย่างไรเพื่อให้เรารู้และเข้าใจภาพรวมของระบบมากยิ่งขึ้นสามารถ maintain ได้ง่าย สามารถหาได้ง่าย ทีมต่าง ๆ ทำงานร่วมกันได้ดีขึ้นรวมทั้งวิเคราะห์ผลกระทบต่าง ๆ จากการแก้ไขได้ดีขึ้นเราจะทำอย่างไรดี
เนื่องจากมีปัญหาในจัดการ OpenAPI หรือ Swagger ที่คุ้นเคยใน FastAPI กันดังนี้ เลยลองมาทำดูแบบง่ายกันหน่อย
มีโอกาสแบ่งปันประสบการณ์เรื่องของ API-First development (Design-First)ซึ่งจะตรงข้ามกับ Code-First ที่มักจะมีขั้นตอนการทำงานดังนี้ แต่แนวทางของ API-First development จะแตกต่างออกไปดังนี้
จากบทความเรื่อง รวม Tips & Tricksในการสร้าง Swagger UI ให้กับ Gin REST API ด้วย Swaggoอธิบายถึงการสร้าง API Documentationโดยทำการสร้างมาจาก Code Annotation ในส่วนของ comment ด้วย command swagซึ่งเป็นแนวทางหนึ่งในการสร้างเอกสารขึ้นมา แต่ก็ยังไม่แนวทางอื่น ๆ ใช้งานเช่นกัน