การ Document API ด้วย Swagger/OpenAPI

หลังจากที่เราได้เรียนรู้เกี่ยวกับการจัดการ Version ของ API ในบทความที่แล้ว (URL Versioning และ Header Versioning) ในบทความนี้ เราจะมาเรียนรู้วิธีการสร้างเอกสาร (Documentation) สำหรับ API ของเราด้วยเครื่องมือที่ชื่อว่า Swagger/OpenAPI ซึ่งเป็นสิ่งสำคัญอย่างยิ่งในการทำให้ API ของเราใช้งานง่ายและเป็นมิตรต่อนักพัฒนาคนอื่นๆ

Swagger/OpenAPI คืออะไร?

Swagger/OpenAPI คือ Specification (ข้อกำหนด) มาตรฐานสำหรับการออกแบบ, สร้าง, Document, และ Consume RESTful APIs เดิมที Swagger เป็นชื่อของเครื่องมือที่ใช้สร้างเอกสาร API แต่ต่อมาได้ถูกเปลี่ยนชื่อเป็น OpenAPI Specification และถูกดูแลโดย OpenAPI Initiative ซึ่งเป็นส่วนหนึ่งของ Linux Foundation อย่างไรก็ตาม คำว่า "Swagger" ยังคงถูกใช้กันอย่างแพร่หลายในการอ้างถึงเครื่องมือและ ecosystem ที่เกี่ยวข้องกับ OpenAPI Specification

ทำไมต้องใช้ Swagger/OpenAPI?

เอกสารที่ถูกต้องและทันสมัย: Swagger/OpenAPI ช่วยให้เราสร้างเอกสาร API ที่ถูกต้องแม่นยำและอัปเดตอยู่เสมอ โดยเอกสารจะถูกสร้างจากโค้ดจริง ทำให้มั่นใจได้ว่าเอกสารจะไม่ล้าสมัย
การค้นหาและทำความเข้าใจ API ได้ง่าย: เอกสาร Swagger/OpenAPI ทำให้ผู้ใช้งาน API สามารถค้นหาและทำความเข้าใจวิธีการใช้งาน API ได้อย่างรวดเร็ว รวมถึง parameters, response formats, และ error codes ต่างๆ
การทดสอบ API ได้ง่าย: Swagger UI (ซึ่งเราจะพูดถึงในภายหลัง) ช่วยให้เราสามารถทดสอบ API endpoints ต่างๆ ได้โดยตรงจาก browser ทำให้การ development และ debugging ง่ายขึ้น
การ Generate Code อัตโนมัติ: Swagger/OpenAPI สามารถใช้ generate code สำหรับ client SDKs ในภาษาต่างๆ ได้ ทำให้การ integrate API เข้ากับ application อื่นๆ ง่ายขึ้น

การสร้าง Swagger/OpenAPI Specification

Swagger/OpenAPI Specification คือไฟล์ที่อธิบายโครงสร้างของ API ของเรา โดยไฟล์นี้มักจะอยู่ในรูปแบบ YAML หรือ JSON ไฟล์นี้จะระบุข้อมูลต่างๆ เช่น:

ข้อมูลทั่วไปของ API (title, description, version)
ข้อมูลเกี่ยวกับ servers ที่ API ทำงานอยู่
ข้อมูลเกี่ยวกับ endpoints ต่างๆ (path, method, parameters, request body, response)
ข้อมูลเกี่ยวกับ authentication methods

มีหลายวิธีในการสร้าง Swagger/OpenAPI Specification:

เขียนด้วยมือ: เราสามารถเขียนไฟล์ YAML หรือ JSON ด้วยมือได้ แต่ต้องมั่นใจว่าไฟล์นั้นถูกต้องตาม OpenAPI Specification
ใช้เครื่องมือ: มีเครื่องมือมากมายที่ช่วยให้เราสร้าง Swagger/OpenAPI Specification ได้ง่ายขึ้น เช่น Swagger Editor, Stoplight Studio
Generate จาก Code: สำหรับภาษาโปรแกรมมิ่งหลายภาษา (รวมถึง PHP) มี libraries ที่สามารถ generate Swagger/OpenAPI Specification จาก code ของเราได้โดยอัตโนมัติ

ในบทความนี้ เราจะเน้นการสร้าง Specification ด้วยมือ เพื่อให้เข้าใจโครงสร้างของมันอย่างละเอียด

ตัวอย่าง Swagger/OpenAPI Specification (YAML)

สมมติว่าเรามี API สำหรับจัดการข้อมูลสินค้า (Products). นี่คือตัวอย่าง Swagger/OpenAPI Specification สำหรับ API นี้:

openapi: 3.0.0
info:
  title: Product API
  description: API สำหรับจัดการข้อมูลสินค้า
  version: 1.0.0
servers:
  - url: http://localhost:8000/api/v1
paths:
  /products:
    get:
      summary: ดึงข้อมูลสินค้าทั้งหมด
      responses:
        '200':
          description: ข้อมูลสินค้าทั้งหมด
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: Product ID
                    name:
                      type: string
                      description: Product name
                    price:
                      type: number
                      format: float
                      description: Product price
  /products/{id}:
    get:
      summary: ดึงข้อมูลสินค้าตาม ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Product ID
      responses:
        '200':
          description: ข้อมูลสินค้า
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Product ID
                  name:
                    type: string
                    description: Product name
                  price:
                    type: number
                    format: float
                    description: Product price
        '404':
          description: ไม่พบสินค้า

คำอธิบาย:

openapi: ระบุ version ของ OpenAPI Specification ที่ใช้ (ในที่นี้คือ 3.0.0)
info: ให้ข้อมูลทั่วไปเกี่ยวกับ API (title, description, version)
servers: ระบุ URL ของ API server
paths: ระบุ endpoints ต่างๆ ของ API
/products: Endpoint สำหรับดึงข้อมูลสินค้าทั้งหมด (GET method)

get: ระบุ HTTP method คือ GET
summary: คำอธิบายสั้นๆ เกี่ยวกับ endpoint
responses: ระบุ HTTP responses ที่เป็นไปได้

200: Response code 200 OK (สำเร็จ)

description: คำอธิบาย response
content: ระบุ content type (application/json) และ schema ของ response

schema: อธิบายโครงสร้างของ JSON response

/products/{id}: Endpoint สำหรับดึงข้อมูลสินค้าตาม ID (GET method)

parameters: ระบุ parameters ที่ endpoint ต้องการ (ในที่นี้คือ `id` ใน path)

in: ระบุตำแหน่งของ parameter (path)
name: ชื่อของ parameter
required: ระบุว่า parameter จำเป็นหรือไม่
schema: อธิบาย type ของ parameter

responses: ระบุ HTTP responses ที่เป็นไปได้

200: Response code 200 OK (สำเร็จ)
404: Response code 404 Not Found (ไม่พบข้อมูล)

ข้อผิดพลาดที่พบบ่อย:

Syntax errors: YAML หรือ JSON มี syntax ที่ต้องปฏิบัติตามอย่างเคร่งครัด การเว้นวรรคผิดพลาด หรือการใช้เครื่องหมายผิด อาจทำให้ไฟล์ไม่ถูกต้อง
Missing required fields: บาง fields ใน OpenAPI Specification เป็น required การละเลย fields เหล่านี้จะทำให้ไฟล์ไม่ถูกต้อง
Incorrect data types: การระบุ data type ของ parameters หรือ response properties ไม่ถูกต้อง อาจทำให้เกิดปัญหาในการ validate API request หรือ response

การใช้ Swagger UI

Swagger UI คือเครื่องมือที่ช่วยให้เราแสดงผล Swagger/OpenAPI Specification ในรูปแบบ interactive และใช้งานง่าย Swagger UI ช่วยให้เรา:

ดูเอกสาร API ในรูปแบบที่สวยงามและเข้าใจง่าย
ทดสอบ API endpoints ต่างๆ ได้โดยตรงจาก browser
Generate client SDKs ในภาษาต่างๆ

วิธีการใช้งาน Swagger UI

ดาวน์โหลด Swagger UI: ดาวน์โหลด Swagger UI จาก เว็บไซต์ Swagger
Extract ไฟล์: Extract ไฟล์ที่ดาวน์โหลดมา
แก้ไข `index.html`: แก้ไขไฟล์ `index.html` ใน folder ที่ extract มา โดยแก้ไข URL ในส่วนของ `url` ให้ชี้ไปยังไฟล์ Swagger/OpenAPI Specification ของเรา

<!DOCTYPE html>
<html>
  <head>
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
    <style>
      html {
        box-sizing: border-box;
        overflow: hidden;
      }

      *,
      *:before,
      *:after {
        box-sizing: inherit;
      }

      body {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>
    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "petstore.json",  // <-- แก้ไขตรงนี้ ให้ชี้ไปยังไฟล์ OpenAPI Specification ของคุณ
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>
  </body>
</html>

ตัวอย่าง: หากไฟล์ OpenAPI Specification ของเราชื่อ `openapi.yaml` และอยู่ใน directory เดียวกับ `index.html` ให้แก้ไขบรรทัด `url: "petstore.json"` เป็น `url: "openapi.yaml"`

เปิด `index.html` ใน Browser: เปิดไฟล์ `index.html` ใน browser ของคุณ คุณจะเห็น Swagger UI แสดงผลเอกสาร API ของคุณ

กรณีใช้งานจริง:

สมมติว่าคุณสร้าง API สำหรับจัดการข้อมูลลูกค้า (Customers). คุณสามารถใช้ Swagger/OpenAPI เพื่อสร้างเอกสาร API ที่อธิบายวิธีการใช้งาน API, parameters ที่ต้องส่ง, และ response formats ที่ API จะส่งกลับมา จากนั้นคุณสามารถใช้ Swagger UI เพื่อแสดงผลเอกสาร API ในรูปแบบที่สวยงามและ interactive ทำให้ทีมพัฒนาของคุณและนักพัฒนาภายนอกสามารถทำความเข้าใจและใช้งาน API ของคุณได้อย่างง่ายดาย

สรุป:

การ Document API ด้วย Swagger/OpenAPI เป็นสิ่งสำคัญในการทำให้ API ของเราใช้งานง่ายและเป็นมิตรต่อนักพัฒนาคนอื่นๆ Swagger/OpenAPI ช่วยให้เราสร้างเอกสาร API ที่ถูกต้องแม่นยำและอัปเดตอยู่เสมอ และ Swagger UI ช่วยให้เราแสดงผลเอกสาร API ในรูปแบบ interactive และใช้งานง่าย ในบทความถัดไป เราจะมาเรียนรู้วิธีการ Test API ด้วย Postman