สองคลิกรู้เรื่อง มาสร้าง API Documentation ด้วย Postman สำหรับคนไม่โค้ดดด

กลับมาพบกับ tester ต๊อกต๋อย อีกครั้งซึ่งสำหรับบล็อกนี้ จะพาไปพบกับความสบายและง่ายขั้นสุดของการทำ documentation ที่ดีที่สุด(มั้ง) แต่ก็มีประโยชน์กับทีมไม่ใช่น้อยๆเลย

<Generate API Documentation by Postman>

https://starkcountyfair.com/annual-meeting-notices/

API Documentation สำคัญหรือป่าวนะ? 🤔

ช่วยให้คนในทีมเข้าใจตรงกัน เป็นตัวกลางที่สามารถทำให้ frontend, backend และ tester ทำงานร่วมกันได้โดยไม่มีข้อโต้แย้ง ถ้าจะแย้งก็ต้องแย้งตั้งแต่รีวิว spec เลยไม่งั้นมันจะเสียเวลา!

สิ่งที่ต้องเตรียมก่อนทำ

1. โปรแกรม Postman พระเอกของบล็อก
2. Specification ของ API ระบบเราอย่างคร่าวๆ ซึ่ง spec คร่าวๆของเราก็ควรมี header, body, response และ url path name

มาเริ่มทำกันเลยยย 👇

1. สร้าง collection ขึ้นมา

2. สร้าง request แล้วใส่ spec ที่ออกแบบคร่าวๆมาลงไป

3. สร้าง example สำหรับเคสต่างๆที่สามารถเกิดขึ้นได้กับ api ของเรา อันนี้อาจจะต้องปรึกษา backend ร่วมกับ tester เพื่อคิดเคสที่จะเกิดขึ้นให้ได้มากที่สุด

4. คลิก Publish Docs เพื่อ generate api document ของเราออกมาาา

5. จากนั้นจะพาไปยังหน้า setting documentation เราสามารถตั้งค่า environment, style document และสามารถ preview ก่อนที่จะ publish ออกมา แต่ถ้าเราไม่ได้อย่างเปลี่ยนแปลงอะไรก็สามารถกด publish collection ได้เลย

6. หลังจากที่เราได้ทำการ publish document ออกมาก เราก็จะได้พบกับ documentation ที่อยู่ในรูปแบบที่เรียบร้อยและดูง่ายขึ้นมาหนึ่งชิ้น — https://documenter.getpostman.com/view/9625258/SzS8tQrQ

ข้อดีของการ generate document ด้วย postman

1. ง่ายต่อการทำ เพราะใครๆก็สามารถเรียนรู้การใช้งานได้อย่างรวดเร็ว
2. สามารถแก้ผ่าน postman ได้ และ update ทันทีหลังจากเราแก้เสร็จ
3. มีรูปแบบที่เรียบร้อยสะอาดตา และอ่านง่ายมากๆ
4. สามารถปรับเปลี่ยน environment หรือ style ได้ตลอดเวลาตามความต้องการ
5. ข้อดีอีกข้อที่เจ้าของบล็อกเพิ่งค้นพบก็คือ ภายในหนึ่ง status code postman สามารถทำการแยกเคสออกจากกันได้ เพียงแค่เพิ่ม example case ลงไป

ข้อเสียของการ generate document ด้วย postman

หลักๆที่เจ้าของบล็อกรู้มาก็คือ เราไม่สามารถทดสอบ response ของ spec ผ่าน document นี้ได้ เนื่องจากการ publish จะเป็นการสร้างแค่ document แต่ไม่ได้ mock api เพื่อให้เราทดสอบได้ ถ้าอยากทดสอบต้องทำการ mock server ขึ้นมาก่อน แล้วถึงจะไปยิงที่ postman ได้ และข้อเสียอีกข้อก็คือข้อจำกัดในการใช้งาน ซึ่งสามารถดูราคาและเลือก plan ที่เหมาะสมกับงานที่เราจะต้องเจอได้

สรุป

จริงๆแล้วในการทำ API Documentation สามารถใช้ได้หลาย tools ไม่ว่าจะเป็น Swagger-UI, ReDoc, DapperDox และอื่นๆที่จขบ.ยังไม่รู้จักอีกมากมาย เพียงแค่เราต้องเลือกใช้ที่เหมาะกับงาน หรือสะดวกเรามากที่สุดเพื่อให้เราสามารถนำไปใช้ต่อได้และมีประโยชน์กับคนในทีมด้วย และสุดท้าย tester ต๊อกต๋อย ขอสรุปสั้นๆให้กับการ generate documentation เพียงสองคลิกของ postman หนึ่งประโยค

ง่ายและดีมีอยู่จริง

บล็อกนี้เป็นเพียงประสบการณ์ส่วนหนึ่งของเจ้าของบล็อก ถ้าผิดพลาดประการใดสามารถแนะนำกันได้นะคะ ขอบคุณที่ติดตาม tester ต๊อกต๋อย นะคะ