รู้หรือไม่ GraphQL รองรับ API Docs ในตัว!
ไม่ว่าเราจะทำโปรเจ็คนี้คนเดียว หรือทำร่วมกับคนอื่น การเขียน API Doc ก็ยังสำคัญเพราะนอกจากจะทำให้คนอื่นสามารถทำความเข้าใจได้ในเวลาที่ต้องนำไปใช้หรือนำไปเขียนต่อแล้ว ก็ยังเป็นเหมือนตัวช่วยฟื้นความจำให้ตัวเราเองด้วย
GraphQL ก็ทำให้การเขียน API Doc ง่ายมากๆ ด้วยการรองรับ API Doc ในตัวโค้ดเลยนั่นเอง
ฟีเจอร์ลับใน TypeDef
เวลาเราเขียน GraphQL API บน Apollo Server เราจะต้องเขียน 2 ส่วนด้วยกัน คือ TypeDef และ Resolver ซึ่ง TypeDef จะเป็นเสมือนแผนผังของ API ที่บอกว่ามี Types และ Resolvers ชื่ออะไรบ้าง Type นี้จะมี field อะไรบ้าง Resolver จะรับค่าอะไรและส่งค่าอะไรกลับไป และ Resolver จะเป็นที่ที่เราเข้าไปเขียนฟังก์ชั่นสำหรับดึงข้อมูลมา
ทีนี้หากเราเข้า Graphql-Playground เราก็สามารถเข้าไปดู API Docs ได้เลยโดยการกดแท็บทางด้านขวา หากมี 2 อันก็ให้กด Docs แต่บางทีจะมีอันเดียวก็กดอันนั้นได้เลยเหมือนกัน
แต่ว่าตอนนี้เรายังรู้แค่แต่ละ Resolver มี parameter อะไรบ้าง และคืนค่าเป็น Type อะไรเท่านั้น ซึ่งต่อให้ตั้งชื่อ Resolver ดีแค่ไหน ก็ยังไม่เพียงพอแน่นอน
หากคุณเห็นกล่องดำในภาพข้างบน ก็คงเอะใจแล้วว่าที่จริงแล้วว่ามันต้องมีวิธีให้เราเขียนคำอธิบายเพิ่มเติมแหละ แต่ทำยังไงละ?
ก็ตรงๆเลยนั่นแหละ!
กลับมาดูที่ TypeDef ของเรากันเลยดีกว่า
จากที่ในตัวอย่าง เราสามารถใส่คำอธิบายเพิ่มเติมได้โดยการใส่ข้อความที่ครอบด้วย "" เหนือสิ่งที่เราอยากอธิบาย หรือหากเราต้องการหลายบรรทัด เราก็ใช้ """ ครอบบนล่างเลย นอกจากนี้แล้ว GraphQL ยังรองรับ Markdown ด้วย!
ก็อย่างที่เห็นว่า GraphQL นั้นรองรับการเขียน API Docs ในตัวอยู่แล้ว และด้วย Markdown เราก็สามารถเขียนคำอธิบายที่ครบและกระชับได้อย่างง่ายดาย
เห็นอย่างนี้แล้วคุณคิดว่ายังไงบ้าง? การรองรับ Markdown นี้เพียงพอมั้ย? ยังรู้สึกว่ามีข้อจำกัดอะไรบ้างหรือไม่? หรือคุณรู้เคล็ดลับในการเขียน API Doc ที่ดีสำหรับ GraphQL อื่นๆมั้ย?
หากคุณมีคำถามหรือข้อเสนอแนะ ก็คอมเม้นต์ด้านล่างเลยค่ะ และถ้าหากบทความนี้ช่วยให้คุณสื่อสารกับเพื่อนในทีมได้ง่ายขึ้น ก็ช่วยปรบมือให้ซักทีสองทีด้วยนะคะ
