OpenAPI และ Swagger คืออะไร? สอนเขียน API Documentation ที่ดีสำหรับ Developer 2026

การพัฒนา API ที่ดีไม่ได้จบแค่เขียน Code ให้ทำงานได้ แต่ต้องมีเอกสารประกอบที่ชัดเจนด้วย เพราะ API ที่ไม่มี Documentation เหมือนกับผลิตภัณฑ์ที่ไม่มีคู่มือ ผู้ใช้ไม่รู้ว่าจะเรียกใช้อย่างไร ส่ง Parameter อะไรบ้าง และจะได้ Response กลับมาในรูปแบบไหน ปัญหานี้ทำให้เกิด OpenAPI Specification ขึ้นมาเป็นมาตรฐานกลางที่ทั้งอุตสาหกรรมยอมรับ

บทความนี้จะสอนทุกอย่างเกี่ยวกับ OpenAPI และ Swagger ตั้งแต่พื้นฐานจนถึงเทคนิคขั้นสูง ครอบคลุมการเขียน Spec, สร้าง Interactive Docs, Generate Client SDK และ Contract Testing พร้อมตัวอย่างที่ใช้ได้จริงในปี 2026

OpenAPI Specification (OAS) คืออะไร?

OpenAPI Specification (เดิมชื่อ Swagger Specification) คือมาตรฐานเปิดสำหรับอธิบาย RESTful API ในรูปแบบที่ทั้งคนและเครื่องอ่านได้ ปัจจุบันเวอร์ชันล่าสุดคือ OAS 3.1 ซึ่งเข้ากันได้กับ JSON Schema draft 2020-12 อย่างสมบูรณ์

OpenAPI Spec ทำหน้าที่เป็น "สัญญา" (Contract) ระหว่าง API Provider กับ API Consumer โดยระบุรายละเอียดทุกอย่างของ API ไว้ในไฟล์เดียว ได้แก่ Endpoints ทั้งหมดที่มี, HTTP Methods ที่รองรับ, Parameters ที่ต้องส่ง, Request Body รูปแบบไหน, Response ที่จะได้กลับมา, Authentication ที่ต้องใช้ และอื่นๆ อีกมากมาย

Swagger vs OpenAPI — ความแตกต่างของชื่อ

หลายคนสับสนระหว่าง Swagger กับ OpenAPI ความจริงคือ Swagger เป็นชื่อเดิมของ Specification นี้ สร้างโดย Tony Tam ในปี 2011 ต่อมาในปี 2015 SmartBear Software ซึ่งเป็นเจ้าของ Swagger ได้บริจาค Specification ให้ OpenAPI Initiative (OAI) ภายใต้ Linux Foundation และเปลี่ยนชื่อเป็น OpenAPI Specification

เขียน OpenAPI Spec — YAML/JSON

OpenAPI Spec เขียนได้ทั้งในรูปแบบ YAML และ JSON แต่ YAML เป็นที่นิยมมากกว่าเพราะอ่านง่าย เขียนสั้นกว่า และไม่ต้องใส่เครื่องหมายคำพูดมากมาย

โครงสร้างพื้นฐาน

# openapi.yaml — ตัวอย่างครบทุกส่วน
openapi: 3.1.0
info:
  title: My Enterprise API
  description: RESTful API สำหรับระบบจัดการผู้ใช้และสินค้า
  version: 1.0.0
  contact:
    name: API Support
    email: api-support@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Development

paths:
  /users:
    get:
      summary: ดึงรายชื่อผู้ใช้ทั้งหมด
      description: ดึงรายการผู้ใช้แบบ Paginated พร้อม Filter
      operationId: getUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: หน้าที่ต้องการ
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: จำนวนรายการต่อหน้า
        - name: search
          in: query
          schema:
            type: string
          description: ค้นหาตามชื่อหรืออีเมล
      responses:
        '200':
          description: สำเร็จ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: สร้างผู้ใช้ใหม่
      operationId: createUser
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              name: "สมชาย ใจดี"
              email: "somchai@example.com"
              role: "user"
      responses:
        '201':
          description: สร้างสำเร็จ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: อีเมลซ้ำ

  /users/{id}:
    get:
      summary: ดึงข้อมูลผู้ใช้ตาม ID
      operationId: getUserById
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: สำเร็จ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

Components — การใช้ซ้ำด้วย $ref

ส่วน components เป็นที่เก็บส่วนประกอบที่ใช้ซ้ำได้ทั่วทั้ง Spec ทำให้ไม่ต้องเขียนซ้ำซ้อน และแก้ไขจุดเดียวก็มีผลทุกที่ที่อ้างถึง

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, moderator]
          default: user
        createdAt:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - email

    CreateUserRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 2
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
          format: password
        role:
          type: string
          enum: [admin, user, moderator]
      required:
        - name
        - email
        - password

    UserListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer
        page:
          type: integer
        lastPage:
          type: integer

    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
        timestamp:
          type: string
          format: date-time

  parameters:
    UserId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: User ID (UUID)

  responses:
    Unauthorized:
      description: ไม่ได้ Login หรือ Token หมดอายุ
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: ไม่พบข้อมูล
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: ข้อมูลไม่ถูกต้อง
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ใส่ JWT Token ที่ได้จาก /auth/login

    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

    oauth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:users: อ่านข้อมูลผู้ใช้
            write:users: สร้าง/แก้ไขผู้ใช้
            admin: เข้าถึงทุกอย่าง

Data Types และ Formats

OpenAPI 3.1 รองรับ Data Types ตาม JSON Schema draft 2020-12 ซึ่งมีความยืดหยุ่นสูง สามารถกำหนด Validation Rules ได้หลากหลาย

Swagger UI — Interactive API Documentation

Swagger UI คือเครื่องมือที่แปลง OpenAPI Spec ให้กลายเป็นหน้าเว็บ Interactive ที่สวยงาม ผู้ใช้สามารถอ่านเอกสาร ดูตัวอย่าง Request/Response และทดลองเรียก API จริงได้เลยจากหน้าเอกสาร

# วิธีติดตั้ง Swagger UI
# 1. ใช้ Docker (แนะนำ)
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/app/openapi.yaml \
  -v ./openapi.yaml:/app/openapi.yaml \
  swaggerapi/swagger-ui

# 2. ใช้ npm package
npm install swagger-ui-dist

# 3. ใช้ CDN ใน HTML
# <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>

Swagger Editor

Swagger Editor เป็น Online Editor ที่ให้เขียน OpenAPI Spec พร้อม Preview แบบ Real-time เข้าใช้งานได้ที่ editor.swagger.io หรือติดตั้งแบบ Self-hosted ก็ได้ มีฟีเจอร์ตรวจสอบความถูกต้องของ Spec อัตโนมัติ แสดง Error ทันทีเมื่อเขียนผิด syntax

Code-first vs Design-first Approach

มีสองวิธีหลักในการสร้าง OpenAPI Spec ซึ่งแต่ละวิธีมีข้อดีข้อเสียต่างกัน

Design-first (API-first)

เขียน OpenAPI Spec ก่อน แล้วค่อย Generate Code หรือเขียน Code ตาม Spec วิธีนี้เหมาะกับทีมที่ต้องการตกลง API Contract ก่อนเริ่มพัฒนา ทำให้ Frontend และ Backend ทำงานคู่ขนานได้ เพราะทั้งสองฝั่งรู้ว่า API หน้าตาเป็นอย่างไรตั้งแต่เริ่มต้น

Code-first

เขียน Code ก่อน แล้ว Generate OpenAPI Spec จาก Code อัตโนมัติ วิธีนี้เหมาะกับทีมที่ต้องการเริ่มพัฒนาเร็ว ไม่ต้องเขียน Spec เอง แต่ข้อเสียคือ Spec อาจไม่สมบูรณ์ถ้าไม่ใส่ Annotation/Decorator ให้ดี

สร้าง OpenAPI จาก Code อัตโนมัติ

NestJS + @nestjs/swagger

// ติดตั้ง
// npm install @nestjs/swagger swagger-ui-express

// main.ts
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

const config = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API description')
  .setVersion('1.0')
  .addBearerAuth()
  .build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);

// DTO พร้อม Swagger Decorators
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';

export class CreateProductDto {
  @ApiProperty({ description: 'ชื่อสินค้า', example: 'iPhone 16' })
  name: string;

  @ApiProperty({ description: 'ราคา', minimum: 0 })
  price: number;

  @ApiPropertyOptional({ description: 'หมวดหมู่' })
  category?: string;
}

// Controller พร้อม Swagger Decorators
@ApiTags('products')
@Controller('products')
export class ProductsController {
  @Post()
  @ApiOperation({ summary: 'สร้างสินค้าใหม่' })
  @ApiResponse({ status: 201, description: 'สร้างสำเร็จ', type: Product })
  @ApiResponse({ status: 400, description: 'ข้อมูลไม่ถูกต้อง' })
  @ApiBearerAuth()
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }
}

FastAPI (Python) — Auto-gen เต็มรูปแบบ

# FastAPI สร้าง OpenAPI Spec อัตโนมัติจาก Type Hints
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI(title="My API", version="1.0.0")

class UserCreate(BaseModel):
    name: str
    email: EmailStr
    password: str

class UserResponse(BaseModel):
    id: str
    name: str
    email: str

@app.post("/users", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate):
    """สร้างผู้ใช้ใหม่ — FastAPI สร้าง OpenAPI Spec ให้อัตโนมัติ"""
    pass

# Swagger UI: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc
# OpenAPI JSON: http://localhost:8000/openapi.json

Spring Boot + springdoc-openapi

// build.gradle
// implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

@RestController
@RequestMapping("/api/users")
@Tag(name = "Users", description = "User management")
public class UserController {

    @Operation(summary = "สร้างผู้ใช้ใหม่")
    @ApiResponse(responseCode = "201", description = "สร้างสำเร็จ")
    @PostMapping
    public ResponseEntity<User> createUser(@Valid @RequestBody CreateUserDto dto) {
        return ResponseEntity.status(201).body(userService.create(dto));
    }
}
// Swagger UI: http://localhost:8080/swagger-ui.html

Generate Client SDK จาก OpenAPI Spec

หนึ่งในพลังที่ยิ่งใหญ่ที่สุดของ OpenAPI คือความสามารถในการ Generate Client SDK อัตโนมัติจาก Spec ทำให้ Frontend หรือ Mobile Developer ไม่ต้องเขียน HTTP Client เอง ได้ Type Safety ครบถ้วน และ Update ตาม API ที่เปลี่ยนไปได้ง่าย

openapi-generator

# ติดตั้ง openapi-generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript Client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/api-client

# Generate Python Client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client

# รองรับภาษามากมาย:
# typescript-axios, typescript-fetch, python, java, kotlin,
# go, rust, swift, dart, csharp, ruby, php และอื่นๆ

Orval — สำหรับ TypeScript โดยเฉพาะ

# ติดตั้ง
npm install orval --save-dev

# orval.config.ts
export default {
  myApi: {
    input: './openapi.yaml',
    output: {
      target: './src/api/generated.ts',
      client: 'react-query',  // หรือ axios, angular, swr
      mode: 'tags-split',
    },
  },
};

# Generate
npx orval

# ผลลัพธ์ — ได้ React Query Hooks พร้อมใช้
// import { useGetUsers, useCreateUser } from './api/generated';
// const { data, isLoading } = useGetUsers({ page: 1, limit: 20 });

API Mocking จาก OpenAPI Spec

เมื่อมี OpenAPI Spec แล้ว สามารถสร้าง Mock Server อัตโนมัติเพื่อให้ Frontend ทดสอบได้ก่อนที่ Backend จะพัฒนาเสร็จ เครื่องมือ Mock ที่ดีจะอ่าน Spec แล้วสร้าง Response ตัวอย่างให้ตาม Schema ที่กำหนดไว้

Prism — Mock Server โดย Stoplight

# ติดตั้ง Prism
npm install -g @stoplight/prism-cli

# รัน Mock Server จาก OpenAPI Spec
prism mock openapi.yaml

# Mock Server จะรันที่ http://localhost:4010
# ทุก Endpoint จะตอบ Response ตาม Schema ที่กำหนดใน Spec
# curl http://localhost:4010/users → ได้ Mock Data

# Dynamic Mode — สร้างข้อมูลสุ่มตาม Schema
prism mock openapi.yaml --dynamic

MSW (Mock Service Worker) — สำหรับ Frontend

// MSW ใช้ Service Worker ดัก HTTP Request ใน Browser
// เหมาะสำหรับ Frontend Testing มาก

// handlers.ts
import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: '1', name: 'สมชาย', email: 'somchai@test.com' },
      { id: '2', name: 'สมหญิง', email: 'somying@test.com' },
    ]);
  }),

  http.post('/api/users', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: '3', ...body }, { status: 201 });
  }),
];

Contract Testing กับ OpenAPI

Contract Testing คือการตรวจสอบว่า API ที่พัฒนาจริงตรงกับ OpenAPI Spec ที่กำหนดไว้หรือไม่ เป็นกระบวนการสำคัญที่ป้องกันไม่ให้ Spec กับ Code ออกนอกลู่นอกทาง โดยเฉพาะเมื่อ API มีการเปลี่ยนแปลงบ่อย

# ใช้ Prism เป็น Proxy Validator
prism proxy openapi.yaml http://localhost:3000

# Prism จะเป็นตัวกลางที่ตรวจสอบทุก Request/Response
# ถ้า Response ไม่ตรงกับ Spec จะแจ้งเตือน

# ใช้ Schemathesis สำหรับ Property-based Testing
pip install schemathesis

# รัน Test อัตโนมัติจาก Spec
schemathesis run http://localhost:3000/openapi.json \
  --validate-schema=true \
  --checks all

# Schemathesis จะสร้าง Request แบบสุ่มตาม Spec
# แล้วตรวจสอบว่า API ตอบกลับถูกต้องหรือไม่

API Versioning ใน OpenAPI

เมื่อ API เปลี่ยนแปลง ต้องมีกลยุทธ์การ Versioning ที่ดี เพื่อไม่ให้ Client เดิมที่ใช้ API เวอร์ชันเก่าพัง OpenAPI รองรับการระบุ Version ได้หลายวิธี

# วิธีที่ 1: URL Path Versioning (แนะนำ)
servers:
  - url: https://api.example.com/v1
  - url: https://api.example.com/v2

# วิธีที่ 2: Header Versioning
# ระบุใน Parameters
parameters:
  - name: Api-Version
    in: header
    schema:
      type: string
      enum: ['1.0', '2.0']

# วิธีที่ 3: แยกไฟล์ Spec ตาม Version
# openapi-v1.yaml
# openapi-v2.yaml

Authentication ใน OpenAPI Spec

OpenAPI รองรับ Security Scheme หลายรูปแบบ สามารถกำหนดได้ทั้งระดับ Global (ทุก Endpoint) และระดับ Operation (เฉพาะบาง Endpoint)

# Security Schemes ที่รองรับ:
components:
  securitySchemes:
    # 1. Bearer Token (JWT)
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

    # 2. API Key
    apiKey:
      type: apiKey
      in: header       # หรือ query, cookie
      name: X-API-Key

    # 3. OAuth 2.0
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          refreshUrl: https://auth.example.com/refresh
          scopes:
            read: อ่านข้อมูล
            write: เขียนข้อมูล
            admin: จัดการระบบ

    # 4. Basic Auth
    basicAuth:
      type: http
      scheme: basic

# ใช้ Global Security (ทุก Endpoint)
security:
  - bearerAuth: []

# หรือใช้เฉพาะบาง Operation
paths:
  /public/status:
    get:
      security: []    # ไม่ต้อง Auth
      summary: Health check

Redoc — Alternative Documentation UI

Redoc เป็นอีกหนึ่งเครื่องมือยอดนิยมสำหรับสร้างเอกสาร API จาก OpenAPI Spec มีข้อดีคือแสดงเอกสารแบบ Three-panel Layout ที่อ่านง่ายมาก เหมาะสำหรับ API สาธารณะที่ต้องการ Documentation ที่สวยงามและเป็นมืออาชีพ

<!-- ใช้ Redoc ง่ายมาก แค่ใส่ Script Tag -->
<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
</head>
<body>
  <redoc spec-url='./openapi.yaml'></redoc>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

Scalar — Modern API Documentation

Scalar เป็นเครื่องมือสร้างเอกสาร API รุ่นใหม่ที่ออกแบบมาให้ทันสมัยและใช้งานง่ายกว่า Swagger UI โดดเด่นด้วย UI ที่สวยงาม Dark Mode ที่ดูดี Client Code Snippets ในหลายภาษา และ Interactive API Testing ที่ลื่นไหลกว่า

# ใช้กับ NestJS
npm install @scalar/nestjs-api-reference

// main.ts
import { apiReference } from '@scalar/nestjs-api-reference';

app.use('/docs', apiReference({
  spec: { url: '/openapi.json' },
  theme: 'purple',
}));

# ใช้กับ Express
npm install @scalar/express-api-reference

app.use('/docs', expressApiReference({
  spec: { content: openApiSpec },
}));

Best Practices สำหรับ API Documentation

การเขียนเอกสาร API ที่ดีไม่ใช่แค่ใส่ข้อมูลครบ แต่ต้องเขียนให้คนอ่านเข้าใจง่ายและนำไปใช้ได้จริง ต่อไปนี้คือ Best Practices ที่ควรปฏิบัติตาม

• ใส่ Description ทุกที่ — ทุก Endpoint, Parameter, Schema ควรมีคำอธิบายเป็นภาษาที่เข้าใจง่าย ไม่ใช่แค่ชื่อ Field
• ใส่ Example ที่สมจริง — อย่าใช้ "string" หรือ 0 เป็นตัวอย่าง ใส่ข้อมูลที่สมจริงเช่น "somchai@example.com" หรือ 299
• ระบุ Error Response ให้ครบ — ไม่ใช่แค่ 200 แต่ต้องระบุ 400, 401, 403, 404, 409, 500 ด้วย พร้อม Schema ของ Error
• ใช้ $ref เพื่อ Reuse — อย่า Copy-paste Schema ใส่ components แล้วอ้างอิงด้วย $ref จะได้แก้ที่เดียวมีผลทุกที่
• จัดกลุ่มด้วย Tags — ใช้ Tags จัดกลุ่ม Endpoint ตาม Resource เช่น Users, Products, Orders ทำให้ค้นหาง่าย
• Version Control Spec ร่วมกับ Code — เก็บ openapi.yaml ไว้ใน Git Repository เดียวกับ Code เพื่อให้ Spec และ Code อยู่ในเวอร์ชันเดียวกันเสมอ
• ทำ CI/CD Validation — ใส่ขั้นตอนตรวจสอบว่า Spec ถูกต้องและ Code ตรงกับ Spec ใน CI/CD Pipeline
• ใช้ operationId ที่สื่อความหมาย — operationId จะถูกใช้เป็นชื่อ Function ใน Generated SDK ดังนั้นตั้งชื่อให้ดี เช่น getUserById แทน get_user_1

สรุป

OpenAPI Specification เป็นมาตรฐานที่ขาดไม่ได้ในการพัฒนา API สมัยใหม่ ไม่ว่าจะใช้ Swagger UI, Redoc หรือ Scalar สำหรับสร้างเอกสาร ใช้ openapi-generator หรือ Orval สำหรับ Generate SDK หรือใช้ Prism สำหรับ Mock และ Contract Testing ทุกอย่างเริ่มต้นจาก OpenAPI Spec ที่ดี

ในปี 2026 การเขียน API โดยไม่มี Documentation ถือว่ายอมรับไม่ได้ ไม่ว่าจะเป็น API ภายในทีมหรือ API สาธารณะ เริ่มต้นด้วยการเขียน OpenAPI Spec สำหรับ API ที่มีอยู่ ลองใช้ Swagger UI หรือ Scalar สร้าง Interactive Docs แล้วลอง Generate Client SDK ให้ทีม Frontend ใช้ คุณจะเห็นว่าประสิทธิภาพการทำงานของทั้งทีมเพิ่มขึ้นอย่างมหาศาล