สร้าง API Document ด้วย Postman

สำหรับคนที่ทำงานฝั่ง Back-end มาก่อนสิ่งที่จะขาดไม่ได้เลยนั่นก็คือการทำ API Document บ้างก็เรียกว่า API Spec แล้วแต่ละที่จะเรียกกัน เดี๋ยวไว้โอกาสหน้าผมจะลองมาเล่าในเรื่องนี้ให้ฟังเพิ่มเติมนะครับ

โดยเครื่องที่ใช้สร้าง API Document ทั่วไปที่หลายคนรู้จักก็มี Swagger , API DOCและอีกมากมายที่ผมไม่ได้กล่าวไว้ แต่ละตัวก็มีจุดเด่นที่เหมาะกับงานที่แตกต่างกันออกไป

แต่วันนี้ผมจะพาทุกคนมาให้รู้วิธีการสร้าง API Document แบบง่ายสุด ๆ ด้วย Postman

ส่วนนี่คือหน้าตาที่เราจะได้ออกมาครับ

https://documenter.getpostman.com/view/2533356/RWTptd4G

หลายคนก็คงแปลกใจว่า เฮ้ย.. เจ้า Postman มันทำได้ด้วยหรอ?
ปกติเราก็เอาไว้ใช้ยิงทดสอบ API ดูเฉย ๆ นี่นา
ผมก็แปลกใจมากครับตอนที่รู้ว่ามันก็สามารถทำได้ ฮ่า ๆ แล้วทำได้นานแล้วด้วยไม่ใช่ของใหม่เลย
เพื่อไม่เป็นการเสียเวลา เราลองมาดูกันเลยครับว่าต้องทำยังไงบ้าง
ผมบอกเลยว่าง่ายมาก ถ้ายิ่งคนใช้มันอยู่แล้วจะพบว่าไม่ได้เพิ่มงานอะไรเยอะเลย

เริ่มแรกเราต้องสร้าง Collection ขึ้นมาเก็บพวก Request ต่าง ๆ ก่อนครับ

ตรงนี้ให้ใส่ชื่อให้เรียบร้อย จากนั้นลองดูตรงกล่องด้านล่างใหญ่ ๆ จะพบว่ามันคือคำอธิบาย ความพิเศษของมันคือเราใส่ Markdown ได้ครับ จะใส่รูป ใส่สีตัวอักษร หรือ ทำตาราง ได้แล้วแต่เราเลย (ข้อเสียคือการไม่มี Live preview เราอาจจะต้องเขียน markdown style จากที่อื่นก่อนแล้วค่อยมาวาง)

ก่อนจะทำการบันทึกให้กดที่ tab ด้านซ้ายเพื่อเพิ่มตัวแปร url ครับ ไว้ใช้ตั้งค่า url ของ Endpoint จะได้ไม่ต้องตามไปนั่งแก้ในทุก Request ของ Collection นี้

หลังจากที่เราได้ Collection ใหม่แล้วก็ลองสร้าง Request ขึ้นมาครับ

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

ก่อนจะทำการบันทึกให้กดที่ tab ด้านซ้ายเพื่อเพิ่มตัวแปร url ครับ ไว้ใช้ตั้งค่า url ของ Endpoint จะได้ไม่ต้องตามไปนั่งแก้ในทุก Request ของ Collection นี้

หลังจากที่เราได้ Collection ใหม่แล้วก็ลองสร้าง Request ขึ้นมาครับ

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

ทำการเพิ่มค่าต่าง ๆ ของ API เราให้เรียบร้อย จากนั้นกด Save ไว้ครับ

จากนั้นกลับมายังกล่องด้านซ้ายแล้วกดตรง  หลัง Collection ที่เราเพิ่งสร้างไป แล้วเลือก Publish Docs จากนั้นมันก็จะเด้งไปหน้าเว็บไซต์ซึ่งตรงนี้ก็อาจจะต้องเข้าสู่ระบบของเว็บ getpostman.com ก่อนน่ะครับ จากนั้นก็จะมีหน้าให้เลือกว่าจะใช้ Environment อะไร ซึ่งมันจะส่งผลกับตัวแปรของ {{url}} ตอนแรกที่เราใส่ไปครับ อาจจะกดข้ามไปก่อนก็ได้ แต่ถ้าทำจริงต้องดูเรื่องนี้เพิ่มครับ


ตัวอย่าง Project ที่เราใช้งานจริงอยู่

บ๊ะ.. เราใช้เวลาไม่ถึง 5 นาที ก็สร้าง API Document ใช้กันในทีมได้แล้ว ซึ่งถ้ามองตัวนี้คือมันเป็น Document ที่มีชีวิตครับ เมื่อทีมใช้ Postman ในการเล่น หรือ ทดสอบก่อนเขียนโปรแกรมอยู่แล้ว ดังนั้นหากตัว API มันไม่ถูกต้อง ทีมก็สามารถแก้จากเครื่องมือนี้ได้เลย (ทุกครั้งที่กด Save มันก็จะไปทำการ publish ขึ้นไปอัพเดทลิงค์ด้านบนด้วย) เพราะ ผมก็เคยเจอบ่อยครั้งที่ตัว API Document มันไม่ตรงกันกับสิ่งที่ API เป็นจริง ๆ อันนี้น่ากลัวมากน่ะครับ


ของดีขนาดนี้ฟรีไหม?

ฟรี… แต่แค่ 1000 view / เดือน สำหรับราคาของ Postman Pro นั้นก็ค่อนข้างสูงทีเดียวครับ ดังนั้น สรุปเลยน่ะครับ ผมว่ามันก็เป็นเครื่องมือที่เหมาะกับบริษัทขนาดเล็ก ที่ต้องการความคล่องตัวในการทำงาน หรือ อาจจะใช้กับโปรเจกต์ขนาดเล็กที่มีทีมงานไม่มาก

สำหรับ Postman เรียกว่ามี Ecosystem ที่ดีเลยทีเดียว เพราะ ตัวเดียวสามารถใช้เขียนเทสระดับ API, สร้าง API Document, สร้าง Mock API server, แชร์ Collection กันภายในทีม และ อีกหลายอย่างที่เกี่ยวกับสร้าง API


ลองเลือกใช้เครื่องมือเจ๋ง ๆ ที่เหมาะกับตัวงาน มากกว่า เอาเครื่องมือเจ๋ง ๆ มาพยายามใช้กับงาน แล้วชีวิตของเราจะสนุกมากขึ้น เชื่อผมซิ

Please follow and like us:

Comments