จากบทความของ “Using OpenAPI to Build Smart APIs for Dumb Machines”
ในบทความนี้จะกล่าวถึงการใช้ OpenAPI ถ้าคุณอยากได้แบบสั้นๆ เราจัดให้
- ในการทำ API Spec เราจะใช้ OpenAPI ซึ่งเป็นเครื่องมือสำคัญที่ควรใช้เพื่อเปลี่ยนภาระในการจัดการจัดทำเอกสารและดำเนินการกับ API ไปยังเครื่องคอมพิวเตอร์และให้พวก developer มีเวลาที่จะเขียน code มากขึ้น
- OpenAPI 3.0 มี feature ที่ทำให้เราทำงานได้ง่ายขึ้น เช่น ย้อน version หรือ generate ออกมาเป็น code ให้
- OpenAPI สามารถทำให้ drive ให้เกิด automation testing โดยการทำตัวเองเป็น mock เสมือนจริงที่ developer ไม่จำเป็นต้อง setup อะไรให้ยุ่งยาก
ทำไมถึงเกิด OpenAPI?
กล่าวได้ว่า “ชาว developer ไม่ได้ชื่นชอบเรื่องการทำงานเกี่ยวกับเอกสาร” ดังนั้นจึงหาวิธีที่จะลดเวลาตรงส่วนนี้ โดยการ generate code API ให้ออกมาในรูปของเอกสาร tool ที่ชื่อ Swagger จึงได้เข้ามาช่วยในจุดนี้ก่อนที่จะถูก rebrand มาเป็นชื่อ OpenAPI ที่อยู่ภายใต้การดูแลของ OpenAPI initiative เพื่อเอามาแก้ปัญหาเรื่อง code อัปเดทแล้ว แต่เอกสารยังไม่ได้อัปเดทตาม
โดยเราสามารถกำหนด API Spec ได้ทั้ง generate ผ่าน UI/สร้างผ่าน file JSON หรือ file yml ได้ ยกตัวอย่าง
หรือสามารถเขียนลงไปใน code แล้วให้ tools generate เอกสารออกมา ซึ่งช่วยแก้ปัญหาเรื่องเอกสารไม่อัปเดท ทำให้เราสามารถจัดการเอกสารได้ทันทีเมื่อมีการแก้ไข code
นอกจากนั้น OpenAPI ยังสามารถสร้าง mock server ขึ้นมาโดยจำลองตัวอย่างข้อมูลจากที่เราสร้าง example ไว้ ทำให้เราสามารถทดสอบได้ง่าย ไม่จำเป็นต้องมีเครื่อง server ในการทดสอบก็ได้
เพิ่มเติม
ถ้าคุณกำลังจะสร้าง API ใหม่ อย่าลืมทำ API description spec ซึ่งการที่เราเริ่มจากสร้าง interface ที่ใช้ในการคุยกันก่อน แล้วค่อยมา implement นั้น เรียกว่า “contract first” ช่วยให้คนที่เกี่ยวข้องสามารถเข้าใจตรงกันได้ และระหว่างพัฒนาสามารถเช็คได้ว่า ส่วนที่ตนทำงานต่อนั้น integrate เข้ากับส่วนอื่นได้หรือป่าว
ฉะนั้นควรจะเริ่มทำ API spec ตอนที่เริ่ม API Project ซึ่งสามารถนำไปสร้างเป็น stubs, code, client ฯลฯ เพื่อที่คนที่เกี่ยวข้องสามารถเข้าใจตรงกันได้และระหว่างพัฒนาสามารถเช็คได้ว่า ส่วนที่ตนทำงานต่อนั้นสามารถ integrate เข้ากับส่วนอื่นได้หรือไม่
การจะทำ “contract first” นั้นขึ้นอยู่กระบวนการของคุณเอง สำหรับองค์กรขนาดใหญ่การทำ “contract first” นั้นอาจะเป็นวิธีที่ดี เพราะถ้ามี API spec ก่อน ทีม client หรือ develop สามารถเอาไปทำก่อนได้โดยการเขียน mock หรือ implement เอาไว้ก่อนได้ และเมื่อได้รับรายละเอียดของ API แล้วสิ่งสำคัญก็คือควรจะทำให้เป็นเวอร์ชั่นปัจจุบันให้มากที่สุด ที่กล่าวมาข้างต้นนั้นสามารถได้มาจาก OpenAPI นั่นเอง
