คู่มือการใช้งาน OpenAPI Validator: ตรวจสอบ API Contract ให้ถูกต้องก่อนขึ้น Production

OpenAPI Specification (หรือที่หลายคนยังเรียกว่า Swagger Specification) เป็นเอกสารที่อธิบาย contract ของ API อย่างเป็นระบบ ทั้ง endpoint, HTTP method, parameters, request body, response และ security scheme เมื่อ specification ถูกต้อง ทีม frontend, backend, QA และระบบที่ใช้สร้างเอกสารหรือ client code จะทำงานจากความเข้าใจเดียวกันได้

แต่ไฟล์ OpenAPI ที่เขียนด้วยมือมีโอกาสผิดพลาดได้ง่าย เช่น ลืมใส่ responses ใช้ชื่อ schema ไม่ตรงกัน กำหนด required ผิดระดับ หรือเขียน YAML indentation ไม่ถูกต้อง OpenAPI Validator ช่วยตรวจสอบ specification เหล่านี้ก่อนที่ความผิดพลาดจะไหลไปถึงขั้นตอน development และ deployment โดยแสดงปัญหาที่ควรแก้ให้เห็นอย่างชัดเจน

OpenAPI Validator เป็นเครื่องมือออนไลน์สำหรับตรวจสอบ OpenAPI document ได้อย่างรวดเร็ว คุณสามารถวาง YAML หรือ JSON ลงใน editor แล้วดูผล validation ได้ทันที เหมาะสำหรับการตรวจสอบระหว่างพัฒนา การ review pull request และการตรวจไฟล์ก่อนนำไปใช้สร้าง API documentation หรือ code generation

ทำไมต้องตรวจสอบ OpenAPI Specification?

การตรวจ specification ไม่ได้มีไว้เพียงเพื่อให้ไฟล์ผ่าน parser เท่านั้น แต่ช่วยป้องกันความไม่สอดคล้องระหว่างเอกสารกับ API ที่ทีมกำลังสร้างด้วย เหตุผลสำคัญมีดังนี้:

• ค้นหา error ตั้งแต่ต้น — พบ syntax หรือโครงสร้างที่ไม่ถูกต้องก่อนเริ่มสร้าง client และ server
• ทำให้ API contract เชื่อถือได้ — ผู้ใช้ API สามารถอ้างอิงชื่อ field, type และ response ได้อย่างมั่นใจ
• ลดการสื่อสารที่คลาดเคลื่อน — ทุกทีมใช้เอกสารชุดเดียวกันแทนการเดาจาก implementation
• ป้องกันเอกสารเสีย — เครื่องมืออย่าง Swagger UI หรือระบบสร้าง SDK อาจทำงานผิดพลาดเมื่อ schema ไม่สมบูรณ์
• ช่วยใน code review — reviewer เห็นข้อผิดพลาดด้าน contract ได้ก่อน merge code
• ประหยัดเวลาในการแก้ปัญหา — แก้ specification ที่ต้นทางง่ายกว่าตามหาสาเหตุจาก error ในหลายระบบภายหลัง

OpenAPI Validator ตรวจสอบอะไรบ้าง?

Validator จะตรวจทั้งรูปแบบเอกสารและความหมายขององค์ประกอบต่าง ๆ ภายใน OpenAPI document โดยทั่วไปสิ่งที่ควรตรวจมีดังนี้:

การผ่าน validation หมายความว่าเอกสารมีโครงสร้างตามกฎที่ validator ตรวจได้ แต่ไม่ได้รับประกันว่า API implementation จะส่งข้อมูลตรงตามเอกสารเสมอ ดังนั้นควรใช้ validator ร่วมกับ integration test และ contract test ด้วย

วิธีใช้ OpenAPI Validator

การตรวจสอบไฟล์ทำได้ในไม่กี่ขั้นตอน:

1. เตรียม OpenAPI document — ใช้ไฟล์ YAML หรือ JSON ที่มี specification ของ API หากเพิ่งเริ่มต้น ควรเริ่มจาก document ขนาดเล็กที่มี endpoint สำคัญหนึ่งหรือสองรายการ
2. เปิด OpenAPI Validator — เข้าเครื่องมือจากเบราว์เซอร์ได้ทันที ไม่ต้องติดตั้ง package หรือสร้าง project เพิ่ม
3. วางเนื้อหาใน editor — คัดลอก OpenAPI document มาวางในช่อง input และตรวจสอบว่าไม่มีข้อความอื่นปนอยู่
4. เลือก format ให้ถูกต้อง — หากเครื่องมือมีตัวเลือก format ให้เลือก YAML หรือ JSON ให้ตรงกับเนื้อหาที่ป้อน
5. อ่านผล validation — แยกดู syntax error, structural error และข้อผิดพลาดใน field ที่ระบุไว้
6. แก้ไขแล้วตรวจซ้ำ — เริ่มจาก error แรกหรือ error ที่เป็นต้นเหตุ จากนั้น validate ใหม่จนไม่พบปัญหา

เมื่อผลตรวจผ่านแล้ว ให้คัดลอก specification ที่แก้ไขเรียบร้อยไปใช้ต่อใน Swagger UI, API documentation, client generator หรือ pipeline ของทีมได้

ตัวอย่าง OpenAPI Document ขั้นพื้นฐาน

ตัวอย่างต่อไปนี้เป็น OpenAPI 3 document ที่มี endpoint สำหรับอ่านข้อมูลผู้ใช้:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
  description: API สำหรับจัดการข้อมูลผู้ใช้
servers:
  - url: https://api.example.com/v1
paths:
  /users/{userId}:
    get:
      summary: ดึงข้อมูลผู้ใช้ตาม ID
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: พบข้อมูลผู้ใช้
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: ไม่พบผู้ใช้
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

จุดที่ควรสังเกตคือ path parameter {userId} มี parameter ชื่อเดียวกันและกำหนด in: path กับ required: true ส่วน response อ้างอิง schema ที่ประกาศไว้ใน components ด้วย $ref ทำให้สามารถนำ schema เดิมไปใช้กับหลาย endpoint ได้

ทำความเข้าใจส่วนสำคัญของ OpenAPI

openapi และ info

ฟิลด์ openapi ระบุ version ของ OpenAPI Specification ที่ใช้ เช่น 3.0.3 หรือ 3.1.0 การเลือก version ต้องสอดคล้องกับเครื่องมือที่ทีมใช้ เพราะบาง generator และ documentation tool รองรับแต่ละ version ไม่เท่ากัน

ส่วน info ใช้บอกข้อมูลของ API อย่างน้อยควรมี title และ version การเพิ่ม description, contact และ license ช่วยให้เอกสารที่สร้างจาก specification มีบริบทครบถ้วนขึ้น แต่ควรแยก API version ใน info.version จาก version ของ OpenAPI specification ให้ชัดเจน

paths และ operation

paths คือแผนผัง endpoint ของ API โดย key ต้องขึ้นต้นด้วย / เช่น /users หรือ /orders/{orderId} ภายใต้แต่ละ path สามารถประกาศ operation เช่น get, post, put, patch และ delete ได้

แต่ละ operation ควรมี summary ที่อ่านสั้น ๆ ได้, description เมื่อจำเป็น, operationId ที่ไม่ซ้ำกัน และ responses ที่อธิบายผลลัพธ์ทุกกรณีสำคัญ การมี operationId ที่สม่ำเสมอเป็นประโยชน์เมื่อสร้าง SDK หรืออ้างอิง operation จากระบบอื่น

Parameters และ path parameters

Parameter ต้องระบุ name และตำแหน่งด้วย in ซึ่งอาจเป็น path, query, header หรือ cookie หาก parameter อยู่ใน path เช่น /users/{userId} ชื่อใน {} ต้องตรงกับ name และต้องตั้ง required: true เสมอ

parameters:
  - name: limit
    in: query
    required: false
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20

ควรกำหนด schema ให้ชัดเจนแทนการปล่อยให้ validator หรือผู้ใช้ API ต้องเดา type เอง รวมถึงระบุ minimum, maximum, pattern หรือ enum เมื่อ API มีข้อจำกัดจริง

Request body และ response

requestBody อธิบายข้อมูลที่ client ส่งเข้ามา ส่วน responses อธิบายข้อมูลที่ server ส่งกลับ โดยแต่ละรายการควรระบุ media type เช่น application/json และ schema ของ payload ให้ครบ หาก endpoint รองรับหลายรูปแบบ ให้ประกาศแต่ละ media type อย่างชัดเจน

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required: [name, email]
        properties:
          name:
            type: string
          email:
            type: string
            format: email

อย่าลืมอธิบาย error response ที่ client อาจพบ เช่น 400, 401, 403, 404 และ 500 การระบุ error schema เดียวกันผ่าน components ทำให้รูปแบบข้อผิดพลาดสม่ำเสมอทั่วทั้ง API

components และ $ref

components เป็นพื้นที่สำหรับ reusable object เช่น schemas, parameters, responses, requestBodies และ securitySchemes การใช้ $ref ลดการเขียนข้อมูลซ้ำและทำให้การแก้ contract ในอนาคตง่ายขึ้น:

components:
  responses:
    NotFound:
      description: ไม่พบ resource ที่ต้องการ

paths:
  /users/{userId}:
    get:
      responses:
        '404':
          $ref: '#/components/responses/NotFound'

ตรวจสอบให้แน่ใจว่า reference path ชี้ไปยัง component ที่มีอยู่จริงและสะกดชื่อเหมือนกันทุกตัวอักษร โดยเฉพาะเมื่อย้าย component ไปไว้ในไฟล์แยก

Error ที่พบบ่อยและวิธีแก้

YAML indentation ไม่ถูกต้อง

YAML ใช้ whitespace เพื่อบอกลำดับชั้น การเยื้องไม่เท่ากันหรือใช้ tab ปนกับ space อาจทำให้ parser อ่านเอกสารไม่ได้ ควรใช้ space จำนวนคงที่ และจัดระดับ key ใต้ parent ให้สม่ำเสมอ

ลืม responses

ทุก operation ต้องมี responses อย่างน้อยหนึ่งรายการ การมีเพียง summary หรือ requestBody ยังไม่เพียงพอ ให้เพิ่ม status code และ description แม้ response นั้นจะไม่มี body ก็ตาม

ประกาศ path parameter ไม่ครบ

หาก path เป็น /products/{id} ต้องมี parameter ชื่อ id ที่ in: path หากใช้ชื่อ productId หรือวาง parameter ไว้ใน query แทน validator จะมองว่า contract ไม่ตรงกัน

$ref ชี้ไปยังตำแหน่งที่ไม่มีอยู่

ตรวจสอบทั้งชื่อ component และเส้นทาง JSON Pointer เช่น #/components/schemas/User ต้องมี components.schemas.User อยู่จริง อย่าลืมว่า YAML และ JSON แยกตัวพิมพ์เล็ก-ใหญ่

ใช้ type หรือ format ไม่สอดคล้องกัน

format ต้องใช้ร่วมกับ type ที่เหมาะสม เช่น format: email ควรอยู่ใต้ type: string และ format: int64 ควรใช้กับ type: integer การใส่ format ที่ไม่เข้ากันอาจทำให้ generator บางตัวสร้าง code ผิดคาด

ใช้ status code เป็นตัวเลขที่ไม่เหมาะสม

Response key ควรเขียนเป็น string เช่น '200' และ '404' เพื่อให้ parser ตีความตรงกัน หลีกเลี่ยงการใส่ข้อความที่ไม่ใช่ status code เว้นแต่เป็น default response ที่ specification รองรับ

ผสม OpenAPI 2.0 กับ OpenAPI 3

OpenAPI 2.0 ใช้ swagger, definitions, parameters และ consumes ในขณะที่ OpenAPI 3 ใช้ openapi, components.schemas, requestBody และ content ตรวจสอบ version ก่อนแก้ไฟล์ และอย่านำโครงสร้างจากคนละ version มาปะปนกัน

แนวทางปฏิบัติที่ดี

• กำหนด versioning strategy ให้ชัดเจน — ระบุ API version ใน server URL หรือ path ตาม convention ของทีม และอัปเดต info.version เมื่อ contract เปลี่ยน
• ตั้งชื่อให้สม่ำเสมอ — ใช้รูปแบบเดียวกันสำหรับ schema, property, operation และ status response เช่น camelCase หรือ snake_case
• เขียน description ที่ช่วยตัดสินใจ — อธิบายหน่วยของตัวเลข ค่า default เงื่อนไขของ field และกรณีที่อาจคืน error แทนการใส่คำอธิบายกว้าง ๆ
• ใช้ reusable components — เก็บ schema, error response และ security scheme ที่ใช้ซ้ำไว้ใน components เพื่อลดความคลาดเคลื่อน
• ตรวจทุกครั้งก่อน commit — รัน OpenAPI Validator ก่อนเปิด pull request และนำ validation ไปไว้ใน CI เมื่อทำได้
• ทดสอบกับ implementation จริง — validation ตรวจเอกสาร ไม่ได้ตรวจว่า server ส่ง payload ตรงตาม schema หรือไม่ ควรมี automated contract test ควบคู่กัน
• ระวัง breaking change — การลบ field, เปลี่ยน type หรือทำ property ที่เคย optional ให้เป็น required อาจกระทบ client เดิม ควร review ผลกระทบก่อน merge
• อย่าใส่ secret ใน specification — ใช้ placeholder สำหรับ token และเก็บ credential จริงใน secret manager หรือ environment variable

Workflow ที่แนะนำสำหรับทีม

1. เขียนหรือแก้ OpenAPI document ใน branch ของงาน
2. ตรวจ syntax และ validation ใน OpenAPI Validator
3. ตรวจ diff ว่ามี endpoint, field หรือ required property เปลี่ยนไปอย่างตั้งใจ
4. สร้าง documentation หรือ client code จาก document ที่ผ่าน validation
5. รัน contract test กับ API implementation
6. ให้ reviewer จากทีมที่ใช้ API ตรวจความหมายของ request และ response
7. รวมเข้า branch หลักและให้ CI ตรวจซ้ำทุกครั้ง

Workflow นี้ช่วยให้ OpenAPI เป็นส่วนหนึ่งของการพัฒนา ไม่ใช่ไฟล์เอกสารที่ถูกอัปเดตหลังจากเขียน code เสร็จแล้วเท่านั้น

เริ่มตรวจสอบ API ของคุณวันนี้

ไม่ว่าคุณจะกำลังเขียน API ใหม่ แก้ endpoint เดิม หรือ review specification จากทีมอื่น การตรวจ contract ก่อนนำไปใช้งานจริงช่วยลดปัญหาได้มาก วาง OpenAPI YAML หรือ JSON ลงใน OpenAPI Validator แล้วตรวจ error ที่พบทีละรายการได้เลย ใช้งานผ่านเบราว์เซอร์ได้ทันทีและเหมาะกับทั้งการตรวจแบบรวดเร็วและการเตรียมไฟล์สำหรับ CI

เครื่องมือที่เกี่ยวข้องที่คุณอาจชอบ:

• JSON Formatter — จัดรูปแบบและตรวจสอบ JSON ให้อ่านง่ายก่อนนำไปใช้ใน API specification
• JSON to TypeScript — สร้าง TypeScript types จาก JSON response เพื่อช่วยตรวจความสอดคล้องของ data model
• YAML to JSON Converter — แปลง YAML เป็น JSON เพื่อดูโครงสร้างและตรวจสอบข้อมูลได้สะดวก

ขอให้ API contract ของคุณชัดเจน ถูกต้อง และดูแลได้ง่าย!