Wongnok — ออกแบบ API spec จากโจทย์จริง

1 · โจทย์สี่บรรทัด — อ่านให้เจอ "คำนาม"

นี่คือโจทย์ที่ผู้สอนให้มาทั้งหมด ไม่มีมากกว่านี้ — และของจริงในที่ทำงานก็ประมาณนี้แหละ คือคนสั่งงานพูดเป็นภาษามนุษย์ ไม่ได้พูดเป็น endpoint

โจทย์ Wongnok Recipes

  เว็บรวมสูตรอาหาร
  ผู้เยี่ยมชมทั่วไปค้นสูตรจากชื่อเมนูหรือวัตถุดิบได้
  ถ้าไม่รู้ชื่อ ค้นจาก "ระยะเวลาที่ใช้ปรุง" และ "ความยากง่าย" ได้
  มีระบบสมาชิก ที่สมัครแล้วสร้าง/แก้/ลบสูตรของตัวเอง
  และให้คะแนนสูตรของคนอื่นได้

วิธีเริ่มที่ใช้ได้จริงมีอยู่วิธีเดียว และมันเชยมาก: ขีดเส้นใต้คำนามทุกคำในโจทย์ แล้วถามทีละคำว่า "ของสิ่งนี้มีตัวตนไหม"
เพราะ REST คือสถาปัตยกรรมที่ทุกอย่างเป็นคำนาม (บทเรียน 33) — ถ้าคุณหาคำนามไม่เจอ คุณจะเผลอไปตั้งชื่อ endpoint ด้วยกริยาทันที แล้วได้ /searchRecipe /createRecipe เหมือนที่ทุกคนเคยทำในโปรเจกต์แรก
สามคำที่ใช้บ่อยมากตั้งแต่บรรทัดนี้ไป — endpoint = ที่อยู่หนึ่งจุดที่ยิงเข้าไปได้ (method + path เช่น GET /recipes) · resource = "ของ" หนึ่งชนิดที่ API เอามาให้จับต้อง เช่น สูตรอาหาร สมาชิก · spec = เอกสารที่บอกว่า API มีเส้นไหนบ้าง แต่ละเส้นรับอะไร ตอบอะไร

สามแถวล่างคือแถวที่คนพลาดกันมากที่สุด และมันพลาดแบบมีแบบแผน: พอโจทย์เขียนว่า "ค้นจากความยากง่ายได้" สมองจะกระโดดไปที่ GET /difficulty/easy/recipes ทันที เพราะมันอ่านแล้วเหมือนภาษาไทยเป๊ะ
แต่ path มีไว้บอกว่า "ของสิ่งนี้อยู่ที่ไหน" ไม่ใช่ "ฉันอยากได้ของแบบไหน" — นั่นคือกฎข้อ 6 (บทเรียน 36): filter ใช้ query

GET /recipes/difficulty/easy
GET /recipes/cooking-time/30
GET /recipes/difficulty/easy/time/30

GET /recipes?difficulty=easy
GET /recipes?max_cooking_minutes=30
GET /recipes?q=กะเพรา&difficulty=easy&max_cooking_minutes=30

2 · resource ที่ "อยู่ลอย ๆ ไม่ได้"

คะแนนกับรายการโปรดต่างจาก recipes ตรงที่มันไม่มีความหมายถ้าไม่มีพ่อแม่
ลองถามตัวเองว่า GET /ratings/88 ควรตอบอะไร — "คะแนน 4 ดาว" เฉย ๆ เนี่ยนะ ของใคร ให้สูตรไหน? มันไม่มีประโยชน์เลยถ้าไม่รู้ว่าเกาะอยู่กับสูตรไหน
นี่คือกฎข้อ 5: ความสัมพันธ์ให้แสดงด้วย path ที่ซ้อนกัน

  /recipes                         ← กองสูตรทั้งหมด (ค้นหาที่นี่)
     │
     └── /recipes/:id              ← สูตรหนึ่งใบ (อ่าน/แก้/ลบที่นี่)
            │
            ├── /recipes/:id/rating     ← คะแนน "ของสูตรใบนี้"
            │
            └── /recipes/:id/favorite   ← ความเป็นรายการโปรด "ของฉัน ต่อสูตรใบนี้"

  /users
     │
     └── /users/:id                ← โปรไฟล์สมาชิกหนึ่งคน

3 · ตาคุณบ้าง — เขียน spec เองก่อนเปิดเฉลย

ส่วนนี้ห้ามข้าม ถ้าเลื่อนไปดูเฉลยเลยคุณจะได้แค่ "เออ ก็สมเหตุสมผลดี" ซึ่งเป็นความรู้สึกที่ไร้ค่าที่สุดในการเรียนออกแบบ
เปิดสมุดหรือไฟล์เปล่า เขียน method + path ให้ครบ 10 บรรทัดข้างล่างก่อน เวลา 5 นาทีพอ

 1. สมาชิกสร้างสูตรอาหารใหม่
 2. ผู้เยี่ยมชมค้นสูตร (ชื่อเมนู / เวลาปรุง / ความยากง่าย)
 3. เปิดดูสูตรหนึ่งใบแบบเต็ม ๆ
 4. เจ้าของสูตรแก้ไขสูตรของตัวเอง
 5. เจ้าของสูตรลบสูตรของตัวเอง
 6. กดสูตรของคนอื่นเข้ารายการโปรด
 7. เอาสูตรออกจากรายการโปรด
 8. ให้คะแนนสูตรของคนอื่น
 9. ดูโปรไฟล์สมาชิก
10. แก้โปรไฟล์ตัวเอง

// Recipes
POST   /recipes                 // 1. สร้าง
GET    /recipes                 // 2. ค้นหา / ดูทั้งหมด
GET    /recipes/:id             // 3. ดูใบเดียว
PUT    /recipes/:id             // 4. แก้
DELETE /recipes/:id             // 5. ลบ

// Favorite
POST   /recipes/:id/favorite    // 6. กดโปรด
DELETE /recipes/:id/favorite    // 7. เอาออก

// Rating
POST   /recipes/:id/rating      // 8. ให้คะแนน

// User
GET    /users/:id               // 9. ดูโปรไฟล์
PUT    /users/:id               // 10. แก้โปรไฟล์

// Auth (ผู้สอนแถมมาให้ ไม่ได้อยู่ใน 10 ข้อ)
GET    /login
GET    /callback
POST   /exchange
GET    /logout

GET    /api/v1/callback
POST   /api/v1/exchange
GET    /api/v1/login
GET    /api/v1/logout
GET    /api/v1/recipes
POST   /api/v1/recipes
DELETE /api/v1/recipes/:id
GET    /api/v1/recipes/:id
PUT    /api/v1/recipes/:id
DELETE /api/v1/recipes/:id/favorite
POST   /api/v1/recipes/:id/favorite
POST   /api/v1/recipes/:id/rating
GET    /api/v1/users/:id
PUT    /api/v1/users/:id
total routes = 14

4 · spec นี้ผ่านกฎ 7 ข้อกี่ข้อ

ตอนนี้เรามี spec แล้ว หน้าที่ต่อไปไม่ใช่รีบเขียนโค้ด แต่คือตรวจมันด้วยกฎที่เราเพิ่งเรียน
และตรวจแบบตรงไปตรงมา — ไม่ใช่หาเรื่องชม และไม่ใช่หาเรื่องด่า

5 · สี่บรรทัดที่ขัดกฎ — และเหตุผลที่มันขัดได้

GET    /login       // กริยา + GET ที่ทำให้เกิดการเปลี่ยนแปลง
GET    /callback    // กริยา
POST   /exchange    // กริยาล้วน ๆ ไม่มีคำนามเลยสักคำ
GET    /logout      // กริยา + GET ที่ทำลาย session

ถ้าเอากฎ 7 ข้อมาจับตรง ๆ สี่บรรทัดนี้ตกทั้งข้อ 1 และข้อ 7 และ /login กับ /logout ยังตกอีกข้อที่หนักกว่านั้น: GET ควรเป็น safe method — คือเรียกกี่ครั้งก็ไม่เปลี่ยนสถานะอะไรในระบบ (บทเรียน 36 เรื่อง idempotency) แต่ GET /logout ทำลาย session ทิ้ง ซึ่งเป็นการเปลี่ยนสถานะเต็มตัว

แล้วทำไมทั้งโลกยังเขียนกันแบบนี้? เพราะสี่เส้นนี้ ไม่ได้ถูกเรียกโดยโค้ดของเรา — มันถูกเรียกโดยเบราว์เซอร์ และเบราว์เซอร์เดินไปหน้าใหม่ด้วย GET เสมอ

  ผู้ใช้กดปุ่ม "เข้าสู่ระบบ"
      │
      │  1. เบราว์เซอร์ navigate ไป  GET /login       ← เราสั่งให้เป็น POST ไม่ได้
      ▼                                                    (การกดลิงก์ = GET เท่านั้น)
  แอปของเรา ตอบ 302 redirect ไปหน้า login ของ Identity Provider
      │
      │  2. ผู้ใช้พิมพ์รหัสผ่านที่ เว็บของ IdP (ไม่ใช่เว็บเรา)
      ▼
  IdP redirect กลับมา  GET /callback?code=xxxx    ← IdP เป็นคนกำหนดว่าเป็น GET
      │                                                    เราแค่ต้องรับให้ได้
      │  3. ตอนนี้เรามีแค่ "code" ยังไม่มี token
      ▼
  โค้ดฝั่งเรา ยิง  POST /exchange  เอา code ไปแลก access token
      │                                        ← ขั้นนี้ โค้ดเราเป็นคนเรียกเอง
      ▼                                          จึงเลือก method ได้อิสระ
  ได้ token → เก็บไว้ → ยิง /api/v1/recipes ต่อได้

// แทน POST /exchange
POST   /auth/tokens

// แทน GET /logout
DELETE /auth/tokens/current

อีกสองจุดที่ควรถกก่อนลงมือเขียน

6 · จาก spec เป็นโค้ดจริง — 2 endpoint

ถึงตรงนี้ spec นิ่งพอจะเขียนโค้ดได้แล้ว ผมเลือกทำสองเส้นที่สอนได้เยอะที่สุด: POST /recipes (มี body ต้อง validate = ตรวจว่าข้อมูลที่ส่งมาถูกกติกาไหม) กับ GET /recipes (มี query — ช่องว่างที่ spec เว้นไว้ในกฎข้อ 6)
โครงไฟล์ยึดตาม บทเรียน 27:

wongnok42/
├── cmd/api/main.go              ← จุดเริ่มโปรแกรม + annotation ระดับ API
├── internal/
│   ├── httputil/response.go     ← รูปแบบ error กลางของทั้ง API
│   └── recipe/
│       ├── dto.go               ← สัญญากับ client (request/response)
│       ├── handler.go           ← Gin handler + annotation ระดับ endpoint
│       └── handler_test.go      ← httptest
└── docs/                        ← swag สร้างให้ ห้ามแก้มือ

เริ่มที่ dto.go — และนี่คือไฟล์ที่สำคัญที่สุดในโปรเจกต์ เพราะมันคือสัญญาเป็นลายลักษณ์อักษรระหว่างเรากับคนที่เรียก API
DTO ย่อจาก Data Transfer Object — แปลตรงตัวคือ "struct ที่มีไว้รับ-ส่งข้อมูล ข้ามเส้นแบ่งเท่านั้น" ไม่ใช่ struct ที่เก็บลง database · เราแยกมันออกมาเพราะ หน้าตาที่ client เห็น ไม่จำเป็นต้องเหมือนหน้าตาที่เราเก็บจริง (เช่น password ที่อยู่ในตารางแต่ห้ามหลุดออกไปใน response)

// internal/recipe/dto.go
package recipe

// CreateRecipeRequest คือ body ที่ POST /recipes รับ
type CreateRecipeRequest struct {
    Name           string `json:"name"            binding:"required"                        example:"ผัดกะเพราหมูสับ"`
    CookingMinutes *int   `json:"cooking_minutes" binding:"required,min=1,max=1440"         example:"15"`
    Difficulty     string `json:"difficulty"      binding:"required,oneof=easy medium hard" example:"easy"`
}

// ListRecipeQuery คือ query string ที่ GET /recipes รับ  ← เติมช่องว่างของกฎข้อ 6
type ListRecipeQuery struct {
    Q                 string `form:"q"`
    Difficulty        string `form:"difficulty"          binding:"omitempty,oneof=easy medium hard"`
    MaxCookingMinutes int    `form:"max_cooking_minutes" binding:"omitempty,min=1,max=1440"`
}

// RecipeResponse คือหน้าตาสูตรอาหารที่ API คืนกลับไป
type RecipeResponse struct {
    ID             string `json:"id"              example:"3f0c1a7e-2b19-4c5e-9f3a"`
    Name           string `json:"name"            example:"ผัดกะเพราหมูสับ"`
    CookingMinutes int    `json:"cooking_minutes" example:"15"`
    Difficulty     string `json:"difficulty"      example:"easy"`
}

สามอย่างที่ตั้งใจใส่ และเหตุผลของแต่ละอัน

ก่อนไป handler ต้องมีอีกไฟล์เล็ก ๆ ก่อน — internal/httputil/response.go เพราะ handler ทุกตัวจะอ้างถึงมันตอนตอบ error
มีแค่ struct เดียว แต่ทำให้ error ทุกอันของทั้ง API หน้าตาเหมือนกันหมด client เขียนโค้ดอ่าน error ครั้งเดียวใช้ได้กับทุก endpoint:

// internal/httputil/response.go
package httputil

// ErrorResponse คือรูปแบบ error เดียวของทั้ง API
type ErrorResponse struct {
    Error string `json:"error" example:"invalid request body"`
}

ต่อด้วย handler — โครงเดียวกับ บทเรียน 38 คือ handler เป็น method บน struct เพื่อให้ฉีด dependency เข้ามาได้:

// internal/recipe/handler.go
package recipe

import (
    "net/http"
    "strconv"
    "strings"

    "github.com/gin-gonic/gin"

    "wongnok42/internal/httputil"   // <module>/internal/httputil — module ชื่อ wongnok42
)

// Handler ถือ "ที่เก็บข้อมูล" ไว้ในตัวเอง — บทนี้คือ slice ธรรมดา
// วันที่ต่อ database จริง ก็เปลี่ยนแค่สอง field นี้เป็น *gorm.DB
type Handler struct {
    store  []RecipeResponse
    nextID int
}

func NewHandler(seed []RecipeResponse) *Handler {
    return &Handler{store: seed, nextID: len(seed) + 1}
}

// Create godoc
//
//	@Summary		สร้างสูตรอาหารใหม่
//	@Description	สมาชิกสร้างสูตรอาหารของตัวเอง
//	@Tags			recipes
//	@Accept			json
//	@Produce		json
//	@Param			request	body		recipe.CreateRecipeRequest	true	"ข้อมูลสูตรอาหาร"
//	@Success		201		{object}	recipe.RecipeResponse
//	@Failure		400		{object}	httputil.ErrorResponse
//	@Security		BearerAuth
//	@Router			/recipes [post]
func (h *Handler) Create(c *gin.Context) {
    var req CreateRecipeRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, httputil.ErrorResponse{Error: err.Error()})
        return
    }
    created := RecipeResponse{
        ID:             strconv.Itoa(h.nextID),
        Name:           req.Name,
        CookingMinutes: *req.CookingMinutes,   // ปลอดภัยแล้ว: required การันตีว่าไม่ nil
        Difficulty:     req.Difficulty,
    }
    h.nextID++
    h.store = append(h.store, created)

    c.JSON(http.StatusCreated, created)   // 201 ไม่ใช่ 200 — บทเรียน 34
}

// List godoc
//
//	@Summary		ค้นหาสูตรอาหาร
//	@Description	ผู้เยี่ยมชมทั่วไปค้นจากชื่อเมนู เวลาปรุง หรือความยากง่ายได้
//	@Tags			recipes
//	@Produce		json
//	@Param			q					query		string	false	"คำค้นจากชื่อเมนู"
//	@Param			difficulty			query		string	false	"ความยากง่าย"	Enums(easy, medium, hard)
//	@Param			max_cooking_minutes	query		int		false	"ใช้เวลาปรุงไม่เกินกี่นาที"
//	@Success		200					{array}		recipe.RecipeResponse
//	@Failure		400					{object}	httputil.ErrorResponse
//	@Router			/recipes [get]
func (h *Handler) List(c *gin.Context) {
    var q ListRecipeQuery
    if err := c.ShouldBindQuery(&q); err != nil {
        c.JSON(http.StatusBadRequest, httputil.ErrorResponse{Error: err.Error()})
        return
    }

    out := make([]RecipeResponse, 0, len(h.store))   // ← บรรทัดนี้มีเหตุผล ดูหัวข้อ 7
    for _, r := range h.store {
        if q.Q != "" && !strings.Contains(r.Name, q.Q) {
            continue
        }
        if q.Difficulty != "" && r.Difficulty != q.Difficulty {
            continue
        }
        if q.MaxCookingMinutes > 0 && r.CookingMinutes > q.MaxCookingMinutes {
            continue
        }
        out = append(out, r)
    }

    c.JSON(http.StatusOK, out)
}

func (h *Handler) Register(rg *gin.RouterGroup) {
    rg.POST("/recipes", h.Create)
    rg.GET("/recipes", h.List)
}

swag init — spec ที่สร้างจากโค้ด ไม่ใช่จากความทรงจำ

ต่อจาก บทเรียน 41 · ชิ้นสุดท้ายที่ยังขาดคือ main.go ซึ่งเก็บ annotation (= คอมเมนต์รูปแบบพิเศษที่ swag อ่านไปสร้างเอกสาร) ระดับทั้ง API (ชื่อ เวอร์ชัน host และนิยามของ BearerAuth ที่ handler อ้างถึงด้วย @Security)
ถ้าไม่มีบล็อก @securityDefinitions ตรงนี้ คำว่า BearerAuth ใน handler จะไม่มีความหมาย:

// cmd/api/main.go
package main

import (
    "github.com/gin-gonic/gin"

    "wongnok42/internal/recipe"
)

//	@title			Wongnok Recipes API
//	@version		1.0
//	@description	API รวมสูตรอาหารของ Wongnok
//	@host			localhost:8080
//	@BasePath		/api/v1

//	@securityDefinitions.apikey	BearerAuth
//	@in							header
//	@name						Authorization
func main() {
    r := gin.Default()
    v1 := r.Group("/api/v1")
    recipe.NewHandler(nil).Register(v1)
    r.Run(":8080")
}

ทีนี้สั่ง swag init ได้แล้ว — ยืนอยู่ที่ root ของโปรเจกต์ (โฟลเดอร์ที่มี go.mod) แล้วรัน · เพราะ main.go ไม่ได้อยู่ที่ root จึงต้องบอกทางให้ swag ด้วย -g:

$ swag init -g cmd/api/main.go
2026/08/20 22:17:38 Generate swagger docs....
2026/08/20 22:17:38 Generate general API Info, search dir:./
2026/08/20 22:17:38 warning: failed to get package name in dir: ./, error: execute go list command, exit status 1, stdout:, stderr:no Go files in <path ของโปรเจกต์คุณ>
2026/08/20 22:17:38 Generating recipe.CreateRecipeRequest
2026/08/20 22:17:38 Generating recipe.RecipeResponse
2026/08/20 22:17:38 Generating httputil.ErrorResponse
2026/08/20 22:17:38 create docs.go at docs/docs.go
2026/08/20 22:17:38 create swagger.json at docs/swagger.json
2026/08/20 22:17:38 create swagger.yaml at docs/swagger.yaml

บรรทัด warning: failed to get package name in dir: ./ ยังขึ้นอยู่ดีแม้คำสั่งจะสำเร็จ — ไม่ต้องตกใจ ดูบรรทัด create ... สามบรรทัดท้ายเป็นหลัก
ทีนี้ส่วนที่น่าสนใจกว่า: เปิด docs/swagger.json ดูว่า binding tag กลายเป็นอะไร

"recipe.CreateRecipeRequest": {
  "type": "object",
  "required": ["cooking_minutes", "difficulty", "name"],
  "properties": {
    "cooking_minutes": {
      "type": "integer",
      "maximum": 1440,
      "minimum": 1,
      "example": 15
    },
    "difficulty": {
      "type": "string",
      "enum": ["easy", "medium", "hard"],
      "example": "easy"
    },
    "name": { "type": "string", "example": "ผัดกะเพราหมูสับ" }
  }
}

7 · เทสที่พิสูจน์ว่า spec เป็นจริง

spec ที่ไม่มีเทสคือความตั้งใจ ไม่ใช่สัญญา
เทสข้างล่างใช้ table-driven (บทเรียน 16) + httptest.NewRecorder (บทเรียน 40) โดยไม่ต้องเปิด server จริง ไม่ต้องมี database

// internal/recipe/handler_test.go
package recipe_test          // _test ต่อท้าย = เทสจากข้างนอก เห็นเฉพาะของที่ export

import (
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"

    "github.com/gin-gonic/gin"
    "github.com/stretchr/testify/assert"

    "wongnok42/internal/recipe"
)

func newRouter() *gin.Engine {
    gin.SetMode(gin.TestMode)          // ปิด log ของ gin ให้ output เทสอ่านออก
    r := gin.New()
    seed := []recipe.RecipeResponse{
        {ID: "1", Name: "ผัดกะเพราหมูสับ", CookingMinutes: 15, Difficulty: "easy"},
        {ID: "2", Name: "แกงมัสมั่นไก่",   CookingMinutes: 90, Difficulty: "hard"},
    }
    recipe.NewHandler(seed).Register(r.Group("/api/v1"))
    return r
}

func do(t *testing.T, method, target, body string) *httptest.ResponseRecorder {
    t.Helper()
    req := httptest.NewRequest(method, target, strings.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    w := httptest.NewRecorder()      // recorder ใหม่ทุกครั้ง — บทเรียน 40
    newRouter().ServeHTTP(w, req)
    return w
}

func TestCreateRecipe(t *testing.T) {
    tests := []struct {
        name     string
        body     string
        wantCode int
    }{
        {"ครบทุกช่อง",          `{"name":"ต้มยำกุ้ง","cooking_minutes":25,"difficulty":"medium"}`, http.StatusCreated},
        {"ไม่ส่งชื่อเมนู",       `{"cooking_minutes":25,"difficulty":"medium"}`,                    http.StatusBadRequest},
        {"difficulty นอกรายการ", `{"name":"ต้มยำกุ้ง","cooking_minutes":25,"difficulty":"insane"}`, http.StatusBadRequest},
        {"cooking_minutes = 0",  `{"name":"ต้มยำกุ้ง","cooking_minutes":0,"difficulty":"easy"}`,    http.StatusBadRequest},
        {"JSON พัง",             `{"name":`,                                                        http.StatusBadRequest},
    }
    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            w := do(t, http.MethodPost, "/api/v1/recipes", tc.body)
            assert.Equal(t, tc.wantCode, w.Code)
            t.Logf("code=%d body=%s", w.Code, w.Body.String())
        })
    }
}

ผลรันจริง (ตัดมาเฉพาะบรรทัด log):

=== RUN   TestCreateRecipe/ครบทุกช่อง
    handler_test.go:53: code=201 body={"id":"3","name":"ต้มยำกุ้ง","cooking_minutes":25,"difficulty":"medium"}
=== RUN   TestCreateRecipe/ไม่ส่งชื่อเมนู
    handler_test.go:53: code=400 body={"error":"Key: 'CreateRecipeRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"}
=== RUN   TestCreateRecipe/difficulty_นอกรายการ
    handler_test.go:53: code=400 body={"error":"Key: 'CreateRecipeRequest.Difficulty' Error:Field validation for 'Difficulty' failed on the 'oneof' tag"}
=== RUN   TestCreateRecipe/cooking_minutes_=_0
    handler_test.go:53: code=400 body={"error":"Key: 'CreateRecipeRequest.CookingMinutes' Error:Field validation for 'CookingMinutes' failed on the 'min' tag"}
=== RUN   TestCreateRecipe/JSON_พัง
    handler_test.go:53: code=400 body={"error":"unexpected EOF"}

ฝั่ง GET — เทสว่า filter ทั้งสามแบบตามโจทย์ทำงานจริง:

=== RUN   TestListRecipes/ไม่ใส่_filter
    code=200 body=[{"id":"1",...,"difficulty":"easy"},{"id":"2",...,"difficulty":"hard"}]
=== RUN   TestListRecipes/ค้นจากชื่อ            // ?q=กะเพรา
    code=200 body=[{"id":"1","name":"ผัดกะเพราหมูสับ","cooking_minutes":15,"difficulty":"easy"}]
=== RUN   TestListRecipes/ค้นจากความยาก         // ?difficulty=hard
    code=200 body=[{"id":"2","name":"แกงมัสมั่นไก่","cooking_minutes":90,"difficulty":"hard"}]
=== RUN   TestListRecipes/ค้นจากเวลาปรุง         // ?max_cooking_minutes=30
    code=200 body=[{"id":"1","name":"ผัดกะเพราหมูสับ","cooking_minutes":15,"difficulty":"easy"}]
=== RUN   TestListRecipes/ไม่มีอะไรตรง           // ?q=พิซซ่า
    code=200 body=[]
=== RUN   TestListRecipes/difficulty_นอกรายการ    // ?difficulty=insane
    code=400 body={"error":"Key: 'ListRecipeQuery.Difficulty' Error:Field validation for 'Difficulty' failed on the 'oneof' tag"}
PASS
ok  	wongnok42/internal/recipe	0.329s

บรรทัด "ไม่มีอะไรตรง → 200 []" คือบรรทัดที่ต้องหยุดอ่าน
ค้นแล้วไม่เจอ ไม่ใช่ 404 — เพราะ resource /recipes มีอยู่จริง เราเข้าถึงมันได้สำเร็จ แค่ผลลัพธ์ว่างเปล่า (บทเรียน 34)
404 เก็บไว้ใช้กับ GET /recipes/9999 ซึ่งคือการขอของที่ไม่มีตัวตน

var a []RecipeResponse                  // nil slice
b := make([]RecipeResponse, 0)          // empty slice

json.Marshal(a)   // -> ?
json.Marshal(b)   // -> ?

=== RUN   TestNilSliceVsEmptySlice
    nilslice_test.go:15: var a []RecipeResponse      -> null
    nilslice_test.go:16: make([]RecipeResponse, 0)   -> []
--- PASS: TestNilSliceVsEmptySlice (0.00s)

DELETE /api/v1/recipes -> code=404 body="404 page not found"

8 · ปิด Day 8 — และของที่ยังไม่ได้สอน

ทั้งวันนี้เดินเป็นเส้นเดียวจากคำถามว่า "API คืออะไร" มาถึงโค้ดที่รันได้: บท 33 ให้ทุกอย่างเป็น resource + method · บท 34 ให้ status code เป็นคำตอบแรกที่ client อ่าน · บท 35 แยกว่าข้อมูลชิ้นไหนควรไปทาง query / body / header · บท 36 ให้กฎการตั้งชื่อกับ idempotency · บท 37 เปิดฝา net/http ให้เห็นว่า server จริง ๆ มีแค่ interface เดียว · บท 38 กับ บท 39 เอา Gin มาลดโค้ดซ้ำด้วย routing / binding / middleware · บท 40 ทำให้ทั้งหมด เทสได้โดยไม่ต้องเปิด server · บท 41 ทำให้เอกสารเกิดจากโค้ดแทนที่จะเกิดจากความทรงจำ · และบทนี้ให้คุณทำทั้งหมดนั้นย้อนกลับ — จากโจทย์ภาษามนุษย์สี่บรรทัด กลายเป็น spec ที่วิจารณ์ได้ แล้วกลายเป็น endpoint ที่มีเทสยืนยัน

ทดสอบความเข้าใจ

อ้างอิง

• MDN — HTTP request methods — นิยามของ safe กับ idempotent ที่ใช้ตัดสิน GET /logout ในหัวข้อ 5
• RFC 6749 §4.1 — Authorization Code Grant — ต้นเหตุที่ /login กับ /callback ถูกบังคับให้เป็น GET
• OpenAPI (Swagger) 2.0 Specification — ที่มาของ required, minimum/maximum, enum ที่ swag สร้างให้จาก binding tag
• swaggo/swag — Declarative Comments Format — รายการ annotation ทั้งหมด รวมถึง Enums(...) ต่อท้าย @Param
• pkg.go.dev — gin.RouterGroup · gin.Engine — HandleMethodNotAllowed อยู่ในหน้านี้
• pkg.go.dev — json.Marshal — เอกสารระบุเองว่า nil slice encode เป็น null
• บทเรียน 36 — กฎการตั้งชื่อ + idempotency · บทเรียน 40 — httptest · บทเรียน 41 — swaggo — สามบทที่บทนี้เอามาต่อกัน