เครื่องมือช่วยสร้าง OpenAPI Specification

วันนี้ Krungsri Nimble จะพามารู้จัก OpenAPI Specification หรือที่รู้จักกันในชื่อ OpenAPI เครื่องมือที่ช่วยให้ ผู้ออกแบบระบบ นักพัฒนาระบบ รวมถึงผู้ที่ต้องเข้ามา Integrate กับระบบนั้นเข้าใจง่ายขึ้นเกี่ยวกับ API Spec

ปัจจุบันนี้จะมี 2 เวอร์ชั่นใหญ่ๆ ที่นิยมใช้งานคือ Swagger 2.0 และ OpenAPI 3

Swagger 2.0 คือ เวอร์ชันเก่าของ OpenAPI และยังถูกนิยมนำมาใช้งานกันจนถึงปัจจุบัน

OpenAPI 3 เป็นเวอร์ชันที่พัฒนาต่อจาก Swagger 2.0 ซึ่งจะเป็นการปรับโครงสร้างใหม่ให้ดูเรียบง่ายกว่าเดิม และมีความยืดหยุ่นสูงขึ้น

โดยวันนี้ Krungsri Nimble จะพาไปรู้จักกับ OpenAPI 3 โดยส่วนประกอบของ OpenAPI 3 นั้นจะมีดังนี้

1. Metadata: ใช้สำหรับประกาศว่าเวอร์ชั่น ของ OpenAPI ที่ใช้อยู่นั้นเป็นเวอร์ชั่นอะไร โดยมีตัวอย่างตามภาพ ซึ่งเวอร์ชั่นที่ประกาศเอาไว้นี้จะเป็นตัวกำหนดโครงสร้างภาพรวมของ API spec ที่จะใช้งานต่อไปนั่นเอง โดย OpenAPI เวอร์ชันนั้นจะใช้ sematic versioning หรือ SemVer เป็นตัวกำหนด เช่น 3.0.0, 3.0.1, 3.0.2 และ 3.0.3

2. Info : ทำหน้าที่สำหรับอธิบายว่า API Spec ชุดนี้ใช้สำหรับทำอะไร หรือมีจุดประสงค์อะไร รวมถึงการประกาศเวอร์ชันของ API Spec ชุดนี้ๆ ด้วย โดยมีตัวอย่างตามภาพ และมีรายละเอียดดังนี้

title: ใช้สำหรับระบุชื่อของ API
description: ใช้สำหรับอธิบายวัตถุประสงค์ของ API หรือ อธิบายว่า API นี้ทำหน้าที่อะไรบ้าง
version: ใช้ระบุเวอร์ชันของ API ตัวนี้

3. Servers : ใช้สำหรับระบุ API server และ base URL ซึ่งสามารถระบุได้มากกว่า 1 servers เพื่อใช้แยกระหว่างแต่ละ environment เช่น production environment และ test environment

4. Paths : คือตัวที่ใช้กำหนด Endpoint ต่างๆ ของ API รวมถึง method หรือ operation ที่สามารถใช้กับ Endpoint นั้นๆ ได้ มีตัวอย่างตามภาพ และจากตัวอย่าง GET /users ที่ประกาศไว้นั้น เราสามารถระบุ response แยกตาม status code ได้ นั่นคือ หาก status code = 200 จะตอบกลับไปยัง client

5. Parameters : สามารถประกาศได้ผ่านทาง URL path เช่น /users/{userId} หรือผ่านทาง query string เช่น /users?role=admin หรือแม้กระทั่ง headers และ cookies ต่างๆ โดยสามารถระบุ parameters บน OpenAPI ได้ดังตัวอย่าง

6. Request Body: ถ้าหาก Endpoint ที่ประกาศไว้ต้องการใช้ค่าจาก Request body เราสามารถประกาศค่าต่างๆ นี้ได้ภายใต้ request Body keyword ดังตัวอย่างตามภาพ

7. Response: สำหรับแต่ละ Endpoint นั้นเราสามารถประกาศค่าที่จะ response กลับไปหา client ได้โดยแบ่งตาม response status code เช่น 200 หรือ 404 โดยมีตัวอย่างตามภาพ

8. Input & Output Models : ส่วนนี้จะเป็นส่วนที่เอาไว้ประกาศ Object ต่างๆ ที่มี Schema เหมือนกัน เช่น Schema ของ User ซึ่งจะประกอบด้วย id และ name เราสามารถประกาศได้ตามภาพ Code block 1 และจากนั้นสามารถนำ object นี้ไปใช้ reference ตามที่ต่างๆ ภายใน OpenAPI Spec ได้ตามภาพ Code block 2

OpenAPI ที่ได้รู้จักเพิ่มเติมกันไป สามารถนำไปประยุกต์ใช้กับงานที่ทำอยู่เพื่อให้เป็นมาตรฐานเดียวกัน และสื่อสารกันง่ายขึ้นได้

ข้อมูลจาก Facebook Krungsri Nimble: https://www.facebook.com/photo/?fbid=389342327300379&set=pcb.389342410633704