Thanawat Wongchai

Posted on Apr 30 • Originally published at apidog.com

แพลตฟอร์ม API สำหรับ Design-First API Workflow

สรุปโดยย่อ (TL;DR)

แนวทาง design-first คือการเขียนข้อกำหนด API ก่อนเขียนโค้ดจริง โดยให้ spec เป็นแหล่งความจริงเดียวสำหรับ mock, เอกสาร, การทดสอบ และ client/server stub บทความนี้สรุปวิธีนำ design-first ไปใช้จริง เกณฑ์เลือกเครื่องมือ และตัวอย่างเวิร์กโฟลว์ด้วย Apidog

ลองใช้ Apidog วันนี้

Apidog

ทดลองใช้ Apidog ฟรี

บทนำ

นักพัฒนาส่วนใหญ่เริ่มจากการสร้าง API แบบ code-first: เขียน route, เพิ่ม annotation, รัน generator แล้วได้เอกสาร วิธีนี้ใช้ได้ดีในช่วงแรก แต่ปัญหาจะเกิดเมื่อ API โตขึ้นและมีหลายทีมทำงานร่วมกัน

ตัวอย่างปัญหาที่พบบ่อย:

เอกสารไม่ตรงกับ response จริง
annotation ล้าสมัย
มีการเปลี่ยน response shape แต่ไม่ได้อัปเดต decorator
frontend ต้องรอ backend เสร็จก่อนจึงเริ่ม integrate ได้
contract ของ API ไม่ชัดเจน ทำให้ breaking change หลุดไป production

แนวทาง design-first แก้ปัญหานี้โดยให้ spec เช่น OpenAPI เป็นแหล่งความจริงเดียว โค้ด, mock, เอกสาร และการทดสอบทั้งหมดอ้างอิงจาก spec เดียวกัน

เป้าหมายคือ:

ออกแบบ API ก่อน
ตรวจสอบ contract ร่วมกัน
สร้าง mock ให้ frontend ใช้ได้ทันที
ให้ backend implement ตาม spec
ใช้ test ตรวจว่าระบบจริงยังตรงกับ spec

ข้อสำคัญคือเครื่องมือต้องทำให้การเขียน spec เร็วพอสำหรับงานจริง ถ้าเขียน spec ใช้เวลา 20 นาที แต่เขียน route ใช้เวลา 5 นาที ทีมจะกลับไปใช้ code-first ทันที

Design-first คืออะไรในทางปฏิบัติ

Design-first ไม่ใช่แค่การเขียน YAML แต่เป็นเวิร์กโฟลว์การพัฒนา API ทั้งชุด

1. ก่อนเขียนโค้ด

เริ่มจากกำหนด OpenAPI spec ให้ครบอย่างน้อย:

path และ HTTP method
path/query/header parameters
request body schema
response schema ของ status code หลัก เช่น 200, 400, 401, 422, 500
authentication requirement
field description และตัวอย่าง response

ตัวอย่าง OpenAPI แบบย่อ:

paths:
  /users/{id}:
    get:
      summary: Get user profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "User profile"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "User not found"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        displayName:
          type: string

การรีวิว spec ในขั้นนี้คือจุดที่ทีมควรตัดสินใจเรื่องสำคัญ เช่น naming, data structure, error format และ pagination pattern

2. ระหว่างการพัฒนา

หลังจาก spec ถูกกำหนดแล้ว ให้ publish ไปยัง mock server ทันที

ผลลัพธ์คือ:

frontend เริ่มพัฒนา UI และ integration จาก mock ได้
backend implement ตาม contract เดียวกัน
QA เห็น request/response ที่คาดหวังตั้งแต่ต้น
product manager หรือ stakeholder อ่านเอกสาร API ได้โดยไม่ต้องรอระบบจริง

3. หลัง implement เสร็จ

ใช้ automated test ตรวจว่า response จริงยังตรงกับ schema หรือไม่ เช่น:

field ที่ required ต้องมีจริง
type ต้องตรงกับ spec
error response ต้องใช้รูปแบบเดียวกัน
status code ต้องตรงกับที่ประกาศไว้

ถ้า implementation เบี่ยงจาก spec ให้ test fail เพื่อจับปัญหาก่อน merge หรือ deploy

4. เมื่อ requirement เปลี่ยน

ลำดับที่ควรทำคือ:

อัปเดต spec
ให้ frontend/backend รีวิวการเปลี่ยนแปลง
อัปเดต mock จาก spec ใหม่
backend ปรับ implementation
test ตรวจ contract อีกครั้ง

อย่าเปลี่ยน implementation เงียบ ๆ แล้วค่อยตามอัปเดตเอกสารทีหลัง เพราะจะทำให้ spec ไม่ใช่แหล่งความจริงอีกต่อไป

แพลตฟอร์ม design-first ควรมีอะไรบ้าง

ไม่ใช่ทุกเครื่องมือ API ที่เหมาะกับ design-first เครื่องมือที่ดีควรช่วยให้ทีมทำงานตาม spec ได้ง่ายและเร็ว

โปรแกรมแก้ไข API แบบภาพ

การเขียน YAML ดิบเหมาะกับบางคน แต่ไม่เหมาะกับทุกทีม โปรแกรมแก้ไขแบบภาพช่วยลด error จาก indentation และทำให้คนในทีมโฟกัสกับ contract แทน syntax

ควรรองรับ:

สร้าง endpoint จากฟอร์ม
กำหนด request/response schema
reuse schema ผ่าน components
validate OpenAPI แบบ real-time
ดู raw YAML/JSON ได้เมื่อจำเป็น

การตรวจสอบ OpenAPI

Spec ควรถูกต้องก่อนนำไปสร้าง mock, docs หรือ test

เครื่องมือควรแจ้งเตือนทันทีเมื่อมีปัญหา เช่น:

$ref ผิด
response ไม่มี schema
parameter required แต่ไม่อยู่ใน path
type หรือ format ไม่ถูกต้อง
schema ใช้ keyword ผิดตำแหน่ง

Mock server จาก spec

หัวใจของ design-first คือเขียน spec แล้วได้ mock ทันที

Mock ที่ดีควร:

สร้าง response ตาม schema
เคารพ type, format, enum, min/max
รองรับ nested object และ array
resolve $ref
ตั้ง rule เฉพาะสำหรับ case พิเศษได้

ตัวอย่างเช่น ถ้า schema ระบุ:

email:
  type: string
  format: email
age:
  type: integer
  minimum: 18
  maximum: 99
status:
  type: string
  enum: [active, inactive]

mock response ควรสร้างข้อมูลที่สอดคล้องกับ constraint เหล่านี้ ไม่ใช่ส่ง string แบบสุ่มที่ผิด schema

เอกสารที่สร้างจาก spec

เอกสารควรเป็นผลลัพธ์จาก spec โดยตรง ไม่ใช่ไฟล์แยกที่ต้องคอยดูแลเอง

เอกสารที่ดีควรแสดง:

endpoint description
parameter table
request body
response schema
example response
authentication requirement

และควรแชร์ลิงก์ให้ stakeholder อ่านได้ตั้งแต่ขั้นออกแบบ

เวิร์กโฟลว์การรีวิวของทีม

Design-first ต้องปฏิบัติกับ spec เหมือนโค้ด:

มีคนเสนอการเปลี่ยนแปลง
มีคนรีวิว
มี discussion
มีประวัติว่าใครเปลี่ยนอะไร
มีการอนุมัติก่อนนำไป implement

เครื่องมือควรรองรับ comment, change tracking และ collaboration แบบ async

Export เป็น OpenAPI มาตรฐาน

Spec ต้องพกพาได้ คุณควร export เป็น OpenAPI 3.x แล้วใช้กับเครื่องมืออื่นได้ เช่น:

code generator
API gateway
test framework
documentation pipeline
CI/CD validation

Apidog ในฐานะแพลตฟอร์ม design-first

สถาปัตยกรรมของ Apidog วาง spec เป็นศูนย์กลาง แท็บ design, mock server, test runner และ documentation เชื่อมกับ API definition เดียวกัน ทำให้ workflow แบบ design-first ใช้งานได้ในเครื่องมือเดียว

โปรแกรมแก้ไข OpenAPI แบบภาพ

Apidog ให้คุณออกแบบ endpoint ผ่าน interface แบบฟอร์ม เช่น:

path
method
parameters
request body
responses
schema
description
validation rule
mock annotation

คุณไม่จำเป็นต้องเขียน YAML เอง ยกเว้นกรณีที่ต้องการแก้ raw spec โดยตรง Apidog มีมุมมอง raw YAML/JSON และซิงก์กับ visual editor

ตัวอย่างการใช้ schema component:

สร้าง component ชื่อ UserProfile
กำหนด field เช่น id, email, displayName
ใช้ $ref ในหลาย endpoint
เมื่อแก้ UserProfile ครั้งเดียว ทุก endpoint ที่อ้างอิงจะเปลี่ยนตาม

แนวทางนี้ช่วยลด duplicate schema และลดความไม่สอดคล้องกันระหว่าง endpoint

เอกสารแบบ real-time

เมื่อแก้ endpoint ใน designer เอกสารจะอัปเดตตามทันที คุณสามารถตรวจได้ว่า API จะถูกแสดงอย่างไรเมื่อ publish

สิ่งที่ควรตรวจในขั้นนี้:

ชื่อ endpoint อ่านเข้าใจหรือไม่
field description ชัดเจนหรือไม่
response example ใช้งานได้จริงหรือไม่
error response มีรูปแบบสม่ำเสมอหรือไม่
frontend เข้าใจ contract โดยไม่ต้องถามเพิ่มหรือไม่

การแชร์ลิงก์เอกสารให้ product manager หรือ frontend lead รีวิวตั้งแต่ต้นช่วยลดการแก้ API ซ้ำระหว่าง sprint

Smart Mock: จาก spec สู่ mock ที่ใช้ได้จริง

เมื่อบันทึก endpoint ใน Apidog mock server จะพร้อมใช้งานทันที URL ของ mock จะแสดงใน interface และ response จะถูกสร้างจาก schema

ตัวอย่างพฤติกรรมที่ mock รองรับ:

format: email ส่งคืน email ที่ถูกต้อง
minimum / maximum ส่งคืนตัวเลขในช่วงที่กำหนด
enum เลือกค่าจาก enum
nested object/array ปฏิบัติตาม schema
$ref ถูก resolve เป็นโครงสร้างจริง

คุณยังตั้ง mock rule สำหรับสถานการณ์เฉพาะได้ เช่น:

ส่ง 404 เมื่อ path parameter เป็น 0
ส่ง payload เฉพาะเมื่อ query parameter มีค่าหนึ่ง
จำลอง error response สำหรับ frontend state
จำลอง pagination response

ตัวอย่าง use case:

GET /users/0

ให้ mock ตอบ:

{
  "code": "USER_NOT_FOUND",
  "message": "User not found"
}

พร้อม status code 404

การรีวิวของทีมและ change tracking

การเปลี่ยนแปลง API spec ใน Apidog มองเห็นได้ใน workspace สมาชิกทีมสามารถ comment ที่ endpoint หรือ field เฉพาะได้ และดูประวัติการเปลี่ยนแปลงได้ว่าใครแก้อะไรเมื่อไหร่

สำหรับทีมที่ใช้ design-first สิ่งนี้ช่วยให้ spec change ผ่านการรีวิวเหมือน code change โดยไม่ต้องแยกไปจัดการในเครื่องมืออื่น

Design-first เทียบกับ Code-first: ข้อแลกเปลี่ยนจริง

Design-first ไม่ได้ดีกว่าเสมอไป เลือกตามบริบทของทีมและระบบ

ข้อดีของ Design-first

frontend และ backend ทำงานคู่ขนานได้
mock ใช้งานได้ตั้งแต่วันแรก
เอกสารแม่นยำ เพราะมาจาก spec
API contract ชัดเจนและตรวจสอบได้
integration issue ถูกจับตั้งแต่ขั้นออกแบบ
breaking change มองเห็นง่ายขึ้น
spec change ผ่านการรีวิวเป็นระบบ

ข้อเสียของ Design-first

ต้องใช้เวลากำหนด spec ก่อนเขียนโค้ด
ทีมต้องเรียนรู้เครื่องมือ spec
ต้องมีวินัยในการรักษา implementation ให้ตรงกับ spec
ถ้ากำหนดรายละเอียดมากเกินไปเร็วเกินไป อาจ lock decision ก่อนเข้าใจ domain ดีพอ

ข้อดีของ Code-first

เริ่มเร็วสำหรับ prototype หรือโปรเจกต์เล็ก
เหมาะกับนักพัฒนาเดี่ยวที่ iterate เร็ว
ไม่ต้องเรียนรู้เครื่องมือออกแบบ API เพิ่ม
implementation เป็นจุดเริ่มต้นโดยตรง

ข้อเสียของ Code-first

เอกสารมักกลายเป็น artifact รองและ drift ได้ง่าย
frontend ต้องรอ backend ก่อนเริ่ม integration
contract เป็น implicit ทำให้ breaking change ตรวจจับยาก
refactor API แล้วต้องอัปเดตเอกสารเอง
mock มักต้องสร้างแยก

โดยทั่วไป ถ้ามีมากกว่าหนึ่งทีมทำงานกับ API เดียวกัน design-first จะให้ผลลัพธ์ดีกว่า โดยเฉพาะฟีเจอร์ที่ frontend/backend ต้องประสานงานใกล้ชิด

เครื่องมือที่รองรับเวิร์กโฟลว์ design-first

Apidog

Apidog รวม visual editor, mock, documentation, testing และ team review ไว้ในเครื่องมือเดียว เหมาะกับทีมที่ต้องการเวิร์กโฟลว์ design-first แบบครบวงจร จุดเด่นคือการสร้าง mock จาก spec ได้ทันทีและเชื่อมกับเอกสารและการทดสอบ

Stoplight Studio

Stoplight Studio เป็น OpenAPI editor ที่แข็งแรง และมี Spectral linting สำหรับบังคับ style guide เหมาะกับองค์กรที่เน้น governance แต่ไม่ได้มี mock server หรือ test runner ในตัวแบบครบวงจร

SwaggerHub

SwaggerHub เป็นแพลตฟอร์ม OpenAPI ที่ใช้แพร่หลายในองค์กร เหมาะกับทีมที่อยู่ใน ecosystem ของ Swagger อยู่แล้ว มีความสามารถด้าน collaboration และ spec management แต่ความสามารถด้าน mock และ testing มีข้อจำกัดกว่าเครื่องมือแบบครบวงจร

Postman พร้อม API Builder

Postman มี API Builder สำหรับสร้าง OpenAPI spec แต่ workflow ระหว่าง design และ Collection อาจไม่เชื่อมกันเท่าเครื่องมือ design-first โดยตรง Mock server ต้องตั้งค่าจาก Collection มากกว่าสร้างอัตโนมัติจาก spec

Insomnia พร้อมโหมดเอกสาร

Insomnia รองรับการแก้ไข OpenAPI และมี mock พื้นฐาน เหมาะกับนักพัฒนาเดี่ยวหรือทีมเล็กที่ต้องการเครื่องมือใช้ง่าย แต่ไม่ได้ครบเท่าแพลตฟอร์ม design-first เฉพาะทาง

วิธีตั้งค่าเวิร์กโฟลว์ design-first ใน Apidog

ขั้นตอนที่ 1: เริ่มจาก spec ไม่ใช่ request collection

สร้างโปรเจกต์ใหม่ แล้วเริ่มที่แท็บ design ก่อน อย่าเริ่มจากการยิง request

อย่างน้อยควรกำหนด:

endpoint path
HTTP method
request parameters
response schema
error response หลัก

เป้าหมายคือให้ทีมเห็น contract ก่อน implementation

ขั้นตอนที่ 2: สร้าง shared component ก่อน

ก่อนเพิ่ม endpoint จำนวนมาก ให้กำหนด schema ที่ใช้ซ้ำ เช่น:

error response
pagination wrapper
user object
common metadata
auth error
validation error

ตัวอย่าง error schema:

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

เมื่อทุก endpoint ใช้ component เดียวกัน error format จะสม่ำเสมอและ frontend handle ได้ง่ายขึ้น

ขั้นตอนที่ 3: สร้าง endpoint และ response schema

สำหรับแต่ละ endpoint ให้กำหนด response ให้ครบมากกว่าหนึ่งกรณี เช่น:

200 success
400 bad request
401 unauthorized
404 not found
422 validation error
500 server error

อย่ากำหนดเฉพาะ happy path เพราะ frontend ต้อง handle error state ด้วย

ขั้นตอนที่ 4: แชร์ mock URL ให้ frontend ตั้งแต่ต้น

หลังบันทึก endpoint ให้คัดลอก mock URL แล้วส่งให้ frontend

ตัวอย่าง frontend สามารถตั้งค่า base URL:

const API_BASE_URL = "https://mock.example.com";

export async function getUser(id: string) {
  const res = await fetch(`${API_BASE_URL}/users/${id}`);
  if (!res.ok) {
    throw new Error("Failed to fetch user");
  }
  return res.json();
}

เมื่อ backend พร้อมแล้ว ค่อยเปลี่ยน API_BASE_URL ไปยัง environment จริง โดย contract ยังเหมือนเดิม

ขั้นตอนที่ 5: รีวิวเอกสารก่อนเขียน implementation

เปิด preview เอกสารแล้วตรวจ:

field ไหนอ่านแล้วกำกวม
response example ตรงกับ use case หรือไม่
naming สอดคล้องกับ endpoint อื่นหรือไม่
error format ใช้ pattern เดียวกันหรือไม่
pagination และ filtering ชัดเจนหรือไม่

ถ้าเอกสารไม่ชัด แปลว่า spec ยังไม่พร้อม

ขั้นตอนที่ 6: ล็อก spec สำหรับ sprint

เมื่อรีวิวเสร็จแล้ว ให้ถือว่า spec เป็น contract ของ sprint นั้น

ถ้าระหว่าง implement พบว่าต้องเปลี่ยน contract ให้ทำตามลำดับนี้:

อัปเดต spec
แจ้ง frontend/backend
รีวิวผลกระทบ
อัปเดต mock
ปรับ implementation
รัน test ตรวจ contract

อย่าเปลี่ยน response จริงโดยไม่แก้ spec

ขั้นตอนที่ 7: ใช้ test ตรวจ schema ใน CI

ตั้ง test ให้ตรวจ response schema ระหว่าง CI เพื่อป้องกัน drift

ตัวอย่างแนวคิดของ pipeline:

name: API Contract Check

on:
  pull_request:
    branches:
      - main

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run API schema tests
        run: |
          echo "Run Apidog test collection or schema validation here"

เป้าหมายคือให้ pull request fail ถ้า response จริงไม่ตรงกับ spec

คำถามที่พบบ่อย

Design-first ใช้ได้กับ REST API เท่านั้นหรือไม่?

ไม่ หลักการ design-first ใช้ได้กับ protocol ใดก็ได้ที่มี contract ชัดเจน เช่น:

REST ด้วย OpenAPI
GraphQL แบบ schema-first
gRPC ด้วย protobuf
event-driven system ด้วย AsyncAPI

Apidog รองรับการออกแบบ REST และ GraphQL ส่วน gRPC ใช้ .proto เป็น contract-first ได้ในลักษณะเดียวกัน

ต้องกำหนดทุก endpoint ก่อนเริ่มพัฒนาหรือไม่?

ไม่จำเป็น คุณสามารถใช้ design-first เฉพาะระดับฟีเจอร์ได้ เช่น ออกแบบ spec สำหรับฟีเจอร์ใหม่ก่อนเขียนโค้ด แม้ส่วนอื่นของ codebase ยังเป็น code-first อยู่ก็ตาม

การนำไปใช้แบบ incremental มักทำได้ง่ายกว่าเปลี่ยนทั้งระบบพร้อมกัน

Design-first ทำงานกับ agile sprint อย่างไร?

ในช่วงต้น sprint ให้ทีมออกแบบ API contract สำหรับฟีเจอร์ที่จะทำ จากนั้น:

frontend ใช้ mock พัฒนา UI
backend implement ตาม spec
QA ใช้เอกสารและ mock เตรียม test case
ทีมรีวิว spec change ระหว่าง sprint เมื่อจำเป็น

การรีวิว API spec จึงกลายเป็นส่วนหนึ่งของ sprint planning หรือ technical design

ถ้า implementation ต้องเบี่ยงจาก spec เดิมทำอย่างไร?

ให้เปลี่ยน spec ก่อน ไม่ใช่เปลี่ยน implementation ก่อน

กระบวนการที่ถูกต้องคือ:

อัปเดต spec
แจ้งผู้เกี่ยวข้อง โดยเฉพาะ frontend
รีวิวผลกระทบ
อัปเดต implementation
รัน test ตรวจ contract

วิธีนี้รักษาให้ spec เป็นแหล่งความจริงต่อไป

สร้าง server stub จาก OpenAPI ที่ export จาก Apidog ได้หรือไม่?

ได้ คุณสามารถ export spec จาก Apidog เป็น OpenAPI 3.x แล้วใช้ code generator มาตรฐาน เช่น openapi-generator เพื่อสร้าง server stub หรือ client SDK ในภาษาและ framework ต่าง ๆ

ตัวอย่างคำสั่งทั่วไป:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client

จัดการ version ของ spec อย่างไร?

Apidog มีประวัติการเปลี่ยนแปลงในโปรเจกต์ สำหรับการเปลี่ยนแปลงใหญ่ที่ต้องให้ v1 และ v2 ใช้งานคู่ขนานกัน การแยกโปรเจกต์หรือ branch จะช่วยให้จัดการ contract แต่ละเวอร์ชันได้ชัดเจน

สรุป

Design-first ต้องลงทุนด้านวินัยตั้งแต่ต้น แต่ช่วยลดต้นทุน integration ได้มาก โดยเฉพาะเมื่อหลายทีมทำงานกับ API เดียวกัน

เวิร์กโฟลว์ที่ควรนำไปใช้คือ:

เขียน spec ก่อน
สร้าง mock จาก spec
ให้ frontend/backend ทำงานคู่ขนาน
รีวิวเอกสารก่อน implement
ตรวจ implementation ด้วย schema test
อัปเดต spec ก่อนทุกครั้งเมื่อ contract เปลี่ยน

เครื่องมือที่ดีควรทำให้ขั้นตอนเหล่านี้ง่าย ไม่เพิ่มภาระให้ทีม โปรแกรมแก้ไขแบบภาพ, mock อัตโนมัติ, เอกสารแบบ real-time และการทดสอบของ Apidog ทำให้ design-first เป็น workflow ที่นำไปใช้ได้จริงในทีมพัฒนา API रोजمر्रा.