Swagger — เอกสารที่ไม่มีวันเก่ากว่าโค้ด

1 · ปัญหาที่ Swagger เกิดมาแก้

ลองนึกภาพจริง ๆ: คุณเขียน POST /api/v1/users เสร็จ แล้วเปิด Google Docs พิมพ์ว่า body ต้องมี name กับ email ส่ง link ให้ frontend
อีกสองสัปดาห์คุณเพิ่ม binding:"required" ที่ email — แล้วลืมกลับไปแก้ Docs

ที่เกิดขึ้นต่อจากนั้นไม่ใช่ “เอกสารไม่อัปเดตนิดหน่อย” แต่คือ: frontend ส่ง request ที่ตรงตามเอกสารเป๊ะ ๆ แล้วได้ 400 กลับไป เขาจะไม่สงสัยเอกสารก่อน เขาจะสงสัยโค้ดตัวเองก่อนเป็นชั่วโมง
นี่คือเหตุผลที่ประโยค “เอกสารที่ไม่ตรงกับโค้ด อันตรายกว่าไม่มีเอกสาร” ไม่ใช่คำสวย ๆ — เอกสารที่ผิดคือ bug ที่ไม่มีใครเห็นว่ามันเป็น bug

2 · OpenAPI คือ “มาตรฐาน” · Swagger คือ “ชุดเครื่องมือ”

สองคำนี้ถูกใช้ปนกันจนคนใหม่งง แยกให้ขาดตั้งแต่ตอนนี้ แล้วทุกอย่างที่เหลือจะเข้าที่:

ส่วนเรื่องเวอร์ชัน เป็นจุดที่คนใหม่พลาดตอนไปหา Google บ่อยมาก เพราะชื่อมันเปลี่ยนกลางคัน:

นี่ไม่ใช่เกร็ดไร้สาระ — มันโผล่ในไฟล์ที่คุณจะได้จริง บรรทัดแรกของ docs/swagger.json ที่ผมรันออกมาคือ:

{
  "swagger": "2.0",
  "info": {
    "description": "API สำหรับจัดการข้อมูลผู้ใช้ของ Wongnok",
    "title": "Wongnok API",
    "contact": {},
    "version": "1.0"
  },
  "host": "localhost:8080",
  "basePath": "/api/v1",
  "schemes": ["http", "https"],
  ...

มันเขียนว่า "swagger": "2.0" ไม่ใช่ "openapi": "3.x"
ถ้าวันหนึ่งคุณเอาไฟล์นี้ไปให้เครื่องมือที่รับแต่ OpenAPI 3 แล้วมันบ่น — คุณจะรู้ทันทีว่าปัญหาอยู่ตรงไหน แทนที่จะงงอยู่ครึ่งวัน

3 · flow ทั้งหมดมี 5 ขั้น และเราแตะแค่ขั้นเดียว

ก่อนอื่นขอนิยามคำที่จะเจอทั้งบท: annotation ในที่นี้คือ คอมเมนต์ Go ธรรมดา ๆ ที่ขึ้นต้นบรรทัดด้วย @ เช่น // @Summary ดึงข้อมูล User
คอมไพเลอร์ Go มองว่ามันเป็นคอมเมนต์เปล่า ๆ ไม่มีความหมาย — มีแต่โปรแกรม swag เท่านั้นที่อ่านมันแล้วเอาไปทำอะไรต่อ

วิธีอ่านแผนภาพ: ไล่จากซ้ายไปขวา ช่องแรกช่องเดียวคือของที่มือเราพิมพ์ ที่เหลือเครื่องสร้างให้หมด

   1                2               3                  4                5
เขียน annotation ─▶ รัน swag init ─▶ ได้โฟลเดอร์ docs/ ─▶ Swagger UI ─▶ เอา spec ไปใช้ต่อ

คอมเมนต์ //  @...   สแกนโค้ด        docs.go            /swagger/         GitLab viewer
เหนือ handler       ทั้งโปรเจกต์     swagger.json       index.html        Postman
                                    swagger.yaml                         openapi-generator

└─ เราเขียนเอง ─┘   └──────────── เครื่องสร้างให้อัตโนมัติ ────────────┘

จำโครงนี้ไว้ให้แม่น เพราะเกือบทุกอาการพังในบทนี้ คือ “ขั้นใดขั้นหนึ่งไม่ได้เกิดขึ้น”:
ขั้น 2 ไม่ได้รัน → เอกสารเป็นของเก่า · ขั้น 3 ไม่มีไฟล์ → UI ไม่มีอะไรอ่าน · ขั้น 4 route ผิด → เปิดหน้าไม่เจอ

4 · ติดตั้งสามตัว — และกับดักเวอร์ชันที่สไลด์ไม่ได้เตือน

ของที่ต้องลงมีสามชิ้น หน้าที่ต่างกันชัดเจน อย่าสับสน:

# 1) swag CLI — โปรแกรมที่อ่านคอมเมนต์ในโค้ดแล้วสร้าง docs/ (ไม่ได้อยู่ใน go.mod)
$ go install github.com/swaggo/swag/cmd/swag@latest
$ swag --version
swag version v1.16.4

# 2) + 3) library ฝั่ง Gin สองตัว — handler ที่เสิร์ฟหน้า Swagger UI (อยู่ใน go.mod)
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

รันที่ไหน? คำสั่ง go install (ข้อ 1) รันจากโฟลเดอร์ไหนก็ได้ เพราะมันลงโปรแกรมลงเครื่อง ไม่เกี่ยวกับโปรเจกต์
แต่ go get (ข้อ 2) ต้องรันในโฟลเดอร์ root ของโปรเจกต์ — โฟลเดอร์ที่มีไฟล์ go.mod อยู่ — เพราะมันไปเขียนบรรทัดใหม่ลงใน go.mod

⚠️ กับดักที่สไลด์ไม่ได้พูดถึง — CLI ใหม่กว่า library แล้ว build พัง

อ่านสองคำสั่งข้างบนอีกรอบ แล้วสังเกตว่ามันไม่ได้คุยกัน:
go install ...@latest ลง CLI รุ่นล่าสุดลงเครื่อง · แต่ go get gin-swagger ลาก github.com/swaggo/swag เวอร์ชันที่มันเลือกให้เข้ามาใน go.mod
บนเครื่องผม gin-swagger v1.6.1 ลาก swag library v1.8.12 เข้ามา ขณะที่ CLI เป็น v1.16.4

docs/docs.go ที่ CLI รุ่นใหม่สร้าง จึงอ้าง field ที่ library รุ่นเก่ายังไม่มี ผลคือ โปรเจกต์คอมไพล์ไม่ผ่าน ทั้งที่คุณยังไม่ได้เขียนโค้ดผิดสักบรรทัด:

$ go test ./cmd/api/
# wongnok/docs
docs/docs.go:169:2: unknown field LeftDelim in struct literal of type "github.com/swaggo/swag".Spec
docs/docs.go:170:2: unknown field RightDelim in struct literal of type "github.com/swaggo/swag".Spec
FAIL	wongnok/cmd/api [build failed]

วิธีอ่าน error นี้ให้เป็น: มันชี้ไปที่ docs/docs.go ซึ่งเป็นไฟล์ที่เครื่องสร้าง ไม่ใช่ไฟล์ที่เราเขียน — พอเห็นบรรทัดแรกเป็น # wongnok/docs ให้คิดถึงเรื่องเวอร์ชันทันที อย่าไปนั่งไล่อ่าน docs.go ทีละบรรทัด (มันไม่ใช่ความผิดของไฟล์นั้น)
ทางแก้ที่ได้ผลจริงคือดึง library ให้ใหม่พอที่จะรู้จัก field ที่ CLI สร้าง:

$ go get github.com/swaggo/swag@latest
go: upgraded github.com/swaggo/swag v1.8.12 => v1.16.6

สังเกตตัวเลขให้ดี: @latest ดึง library ไปถึง v1.16.6 ซึ่งใหม่กว่า CLI ที่เป็น v1.16.4 ด้วยซ้ำ — แล้ว build ก็ผ่านปกติ
เพราะทิศที่พังมีทิศเดียว คือฝั่ง CLI สร้าง field ที่ library ยังไม่รู้จัก · เป้าหมายจึงไม่ใช่ “ทำให้เลขตรงกันเป๊ะ” แต่คืออย่าปล่อยให้ library เก่ากว่า CLI

5 · ต่อ Swagger UI เข้ากับ Gin — สองบรรทัดที่คนพลาดมากที่สุด

โค้ดที่ต้องเติมใน cmd/api/main.go สั้นมาก แต่มีสองจุดที่ผิดแล้วไม่มีใครเตือน:

package main

import (
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"

    _ "wongnok/docs"          // ← จุดที่ 1: blank import
    "wongnok/internal/user"
)

func main() {
    router := gin.Default()
    userHandler := user.NewHandler()

    v1 := router.Group("/api/v1")
    {
        v1.POST("/users", userHandler.Create)
        v1.GET("/users/:id", userHandler.FindByID)
    }

    // ← จุดที่ 2: ต้องมี *any ต่อท้าย
    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    router.Run(":8080")
}

นี่คือ main.go เดิมจาก บทเรียน 38 / บทเรียน 39 ที่เติมเข้าไปแค่สองบรรทัดที่มีคอมเมนต์ ← กำกับ (บวก import อีกสามบรรทัด) — ไม่ต้องสร้างไฟล์ใหม่
เมื่อทุกอย่างครบแล้ว วิธีดูผลคือรัน go run ./cmd/api แล้วเปิดเบราว์เซอร์ไปที่ http://localhost:8080/swagger/index.html

จุดที่ 1 — _ "wongnok/docs" ทำไมต้อง import ของที่ไม่ได้ใช้

ตอน swag init ทำงาน มันสร้าง docs/docs.go ขึ้นมา ข้างในไฟล์นั้นมี func init() ที่เอา spec ไปลงทะเบียนไว้ในตัวแปรกลาง ของ library swaggo/swag
ทีนี้ Go มีกฎว่า package ที่ไม่มีใคร import จะไม่ถูกรวมเข้าไปในไบนารีเลย — init() ก็เลยไม่เคยทำงาน
_ (blank identifier) แปลว่า “ฉันไม่ได้จะเรียกอะไรจาก package นี้ แต่ฉันต้องการผลข้างเคียงของ init()”
เป็นเทคนิคเดียวกับที่ database driver ใช้ — ถ้าเคยเห็น _ "github.com/lib/pq" ก็คืออันนี้

// เคส A — route "/swagger/*any" + มี blank import ครบ
GET /swagger/index.html
GET /swagger/doc.json

// เคส B — route "/swagger" เฉย ๆ (ลืม *any)
GET /swagger/index.html

// เคส C — route "/swagger/*any" แต่ไฟล์ที่ตั้ง router ไม่ได้ import _ "wongnok/docs"
GET /swagger/index.html
GET /swagger/doc.json

// เคส A — ครบทุกอย่าง
[/swagger/*any] GET /swagger/index.html -> 200  body="\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>… <title>Swagger UI</title>…"
[/swagger/*any] GET /swagger/doc.json  -> 200  body="{\n \"schemes\": [\"http\",\"https\"],\n \"swagger\": \"2.0\",\n \"info\": {…"

// เคส B — ลืม *any
[/swagger เฉย ๆ]  GET /swagger/index.html -> 404  body="404 page not found"

// เคส C — ไม่มี blank import
ไม่มี blank import — GET /swagger/index.html -> 200  body="\n<!DOCTYPE html>… <title>Swagger UI</title>…"
ไม่มี blank import — GET /swagger/doc.json  -> 500  body=""

จุดที่ 2 — ทำไมต้อง /swagger/*any

จาก บทเรียน 38 เรารู้ว่า Gin มี path parameter สองแบบ: :name จับหนึ่งช่วง · *name จับทุกอย่างที่เหลือรวม /
Swagger UI ไม่ใช่หน้าเดียว มันโหลดไฟล์ย่อยเป็นกอง — index.html, doc.json, swagger-ui.css, ไฟล์ JS อีกหลายตัว
route /swagger เฉย ๆ ตรงกับ path เดียวคือ /swagger พอดิบพอดี พอ browser ขอ /swagger/index.html Gin หาไม่เจอ → 404 ตามผลรันข้างบน

6 · General API Info — ข้อมูลหัวเอกสาร เขียนครั้งเดียว

annotation ชุดนี้เขียนเหนือ func main() และมีที่เดียวในทั้งโปรเจกต์ มันอธิบาย API ทั้งตัว ไม่ใช่ endpoint ใดอันหนึ่ง

//	@title			Wongnok API
//	@version		1.0
//	@description	API สำหรับจัดการข้อมูลผู้ใช้ของ Wongnok
//	@host			localhost:8080
//	@BasePath		/api/v1
//	@schemes		http https

//	@securityDefinitions.apikey	BearerAuth
//	@in							header
//	@name						Authorization
//	@description				ใส่ค่าเป็น "Bearer {token}"
func main() { ... }

มันมีสองก้อน แยกด้วยบรรทัดว่าง — ก้อนบนคือข้อมูลหัวเอกสาร (ตารางข้างล่างอธิบายทีละบรรทัด) · ก้อนล่างสี่บรรทัด (@securityDefinitions.apikey / @in / @name / @description) คือเรื่องการล็อกอิน ข้ามไปก่อนได้ เดี๋ยวหัวข้อ 7.3 จะอธิบายว่ามันทำให้เกิดอะไรขึ้นบนหน้าจอ

7 · annotation ระดับ endpoint

ชุดนี้เขียนเหนือ handler แต่ละตัว นี่คือของจริงจาก internal/user/handler.go ที่ผมรัน swag init ผ่านแล้ว:

// FindByID godoc
//
//	@Summary		ดึงข้อมูล User รายคน
//	@Description	ค้นหา User จาก UUID แล้วคืนข้อมูลกลับมา
//	@Tags			users
//	@Produce		json
//	@Param			id	path		string	true	"User ID (UUID)"	format(uuid)
//	@Success		200	{object}	user.UserResponse
//	@Failure		400	{object}	httputil.ErrorResponse
//	@Failure		404	{object}	httputil.ErrorResponse
//	@Security		BearerAuth
//	@Router			/users/{id} [get]
func (handler *Handler) FindByID(ctx *gin.Context) { ... }

7.1 · @Param มี 6 ช่อง คั่นด้วยช่องว่าง

@Param   <ชื่อ>   <paramType>   <dataType>   <บังคับ?>   "<คำอธิบาย>"   <attribute>
            │           │              │            │             │              │
            │           │              │            │             │              └─ Enums(), default(), format(), minimum()
            │           │              │            │             └─ ข้อความที่ขึ้นใน Swagger UI (ต้องมี " ")
            │           │              │            └─ true / false
            │           │              └─ int, string, bool หรือชื่อ struct
            │           └─ path | query | header | body | formData
            └─ ชื่อที่ client ส่งมา

ช่องที่คนสับสนคือช่องที่ 2 (paramType) กับช่องที่ 3 (dataType) — ช่องที่ 2 บอกว่า “ค่านี้เดินทางมาทางไหน” ตรงกับที่เรียนไปใน บทเรียน 35 เป๊ะ ๆ:

ผมเขียน endpoint ค้นหาเพิ่มหนึ่งอันเพื่อยิงทุกช่องพร้อมกัน แล้วรัน swag init ดูของจริง:

//	@Param		q				query		string	false	"คำค้นจากชื่อ"
//	@Param		status			query		string	false	"สถานะ"			Enums(active, banned)	default(active)
//	@Param		limit			query		int		false	"จำนวนต่อหน้า"	minimum(1)	maximum(100)	default(20)
//	@Param		X-Request-ID	header		string	false	"id สำหรับ trace"
//	@Success	200				{array}		user.UserResponse
//	@Router		/users [get]

ได้ parameters ใน docs/swagger.json ออกมาแบบนี้ (ตัดมาจากไฟล์จริง):

[
  { "type": "string", "description": "คำค้นจากชื่อ", "name": "q", "in": "query" },
  { "enum": ["active", "banned"], "type": "string", "default": "active",
    "description": "สถานะ", "name": "status", "in": "query" },
  { "maximum": 100, "minimum": 1, "type": "integer", "default": 20,
    "description": "จำนวนต่อหน้า", "name": "limit", "in": "query" },
  { "type": "string", "description": "id สำหรับ trace", "name": "X-Request-ID", "in": "header" }
]

สังเกตสองอย่าง: Enums(active, banned) กลายเป็น "enum": [...] ที่ Swagger UI จะเรนเดอร์เป็นช่อง dropdown ให้เลือกไม่ใช่ช่องพิมพ์เปล่า · และ minimum(1) maximum(100) โผล่ครบทั้งคู่
attribute พวกนี้เขียนเพิ่มไม่กี่ตัวอักษร แต่ประหยัดคำถามจาก frontend ไปได้เป็นสิบข้อความ

7.2 · @Success / @Failure — บอกว่าคืนอะไรกลับไป

@Success  <httpCode>  {<รูปแบบ>}  <dataType>

ทำไมต้องมี httputil.ErrorResponse แยกออกมาเป็น package กลาง?
เพราะทุก endpoint ในระบบควรคืน error รูปแบบเดียวกัน frontend จะได้เขียนโค้ดอ่าน error ครั้งเดียวใช้ได้ทั้งเว็บ — ตรงกับเรื่อง response contract ใน บทเรียน 34
โครงมันเรียบง่ายมาก:

package httputil

// ErrorResponse คือรูปแบบ error ที่ทุก endpoint ใช้ร่วมกัน
type ErrorResponse struct {
    Message string `json:"message" example:"user not found"`
}

7.3 · @Security BearerAuth — ปุ่ม Authorize

ทำงานเป็นคู่ 2 จุด ขาดจุดใดจุดหนึ่งก็ไม่เกิดผล:
1. ประกาศ @securityDefinitions.apikey BearerAuth เหนือ func main() (หัวข้อ 6) — บอกว่า “ระบบนี้มีวิธีล็อกอินชื่อ BearerAuth ซึ่งส่งมาทาง header ชื่อ Authorization”
2. ใส่ @Security BearerAuth เหนือ handler ที่ต้องล็อกอิน — บอกว่า “อันนี้แหละที่ต้องใช้”

ผลใน docs/swagger.json ที่ได้จริง แยกกันคนละที่ตามนั้น:

// ระดับเอกสาร มาจากข้อ 1
"securityDefinitions": {
  "BearerAuth": {
    "description": "ใส่ค่าเป็น \"Bearer {token}\"",
    "type": "apiKey",
    "name": "Authorization",
    "in": "header"
  }
}

// ระดับ endpoint มาจากข้อ 2 (อยู่ใต้ paths./users/{id}.get)
"security": [ { "BearerAuth": [] } ]

ผลที่ผู้ใช้เห็นบนหน้า Swagger UI: มีปุ่ม Authorize มุมขวาบน · ใส่ token ครั้งเดียวใช้ได้ทุก endpoint · endpoint ที่ล็อกอินจะมีรูปกุญแจ · กด Try it out แล้วมันแนบ header Authorization ให้เอง
ประโยชน์จริงคือ frontend ทดลอง endpoint ที่ต้องล็อกอินได้โดยไม่ต้องเปิด Postman

8 · struct tag ที่มีผลกับเอกสาร

จาก บทเรียน 13 เรารู้จัก json: tag และจาก บทเรียน 39 รู้จัก binding: tag แล้ว
ข่าวดีคือ swag อ่านทั้งสองอันที่มีอยู่แล้ว โดยเราไม่ต้องเขียนอะไรซ้ำ — มีของใหม่แค่ example: ตัวเดียว

type CreateUserRequest struct {
    Name  *string `json:"name" example:"สมชาย ใจดี"`
    Email string  `json:"email" binding:"required,email" example:"somchai@pea.co.th"`
}

type UserResponse struct {
    ID    string `json:"id" example:"3f0c1a7e-2b19-4c5e-9f3a"`
    Name  string `json:"name,omitempty" example:"สมชาย ใจดี"`
    Email string `json:"email" example:"somchai@pea.co.th"`
}

รัน swag init แล้วเปิด docs/swagger.json ได้ของจริงแบบนี้:

"user.CreateUserRequest": {
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string", "example": "somchai@pea.co.th" },
    "name":  { "type": "string", "example": "สมชาย ใจดี" }
  }
}

ข้อ 3 คือหัวใจของทั้งเรื่อง: กลับไปดูสถานการณ์ในหัวข้อ 1 อีกที — วันที่คุณเติม binding:"required" ที่ email เอกสารเปลี่ยนตามไปเองในการ generate ครั้งถัดไป ไม่มี Google Docs ให้ลืมแก้อีกแล้ว

9 · swag init — พิมพ์ตกไปนิดเดียว แล้วไม่ได้อะไรเลย

รันจากโฟลเดอร์ไหน? รันที่ root ของโปรเจกต์ เสมอ — โฟลเดอร์ที่มี go.mod อยู่ ไม่ใช่ใน cmd/api/
ดูบรรทัด search dir:./ ในผลรันข้างล่างเป็นหลักฐาน: ./ คือโฟลเดอร์ที่คุณกำลังยืนอยู่ตอนกด Enter

โครง wongnok วาง main.go ไว้ที่ cmd/api/main.go ตาม บทเรียน 27 ซึ่งเป็นเรื่องดี — แต่มันชนกับค่า default ของ swag ตรง ๆ

$ swag init
2026/08/20 22:15:46 Generate swagger docs....
2026/08/20 22:15:46 Generate general API Info, search dir:./
2026/08/20 22:15:46 warning: failed to get package name in dir: ./, error: execute go list command, exit status 1, stdout:, stderr:no Go files in <โปรเจกต์>
2026/08/20 22:15:46 cannot parse source files <โปรเจกต์>/main.go: open <โปรเจกต์>/main.go: no such file or directory

$ ls docs
ls: docs: No such file or directory

ไม่มีโฟลเดอร์ docs/ เกิดขึ้นเลยแม้แต่ไฟล์เดียว
สไลด์สรุปอาการนี้ว่า “หา @title ไม่เจอ” ซึ่งถูกในเชิงผลลัพธ์ แต่ข้อความจริงตรงกว่านั้นมาก — มันบอกตรง ๆ ว่าหาไฟล์ main.go ที่ root ไม่เจอ
เหตุผล: swag init --help เขียนไว้ว่า --generalInfo value, -g value Go file path in which 'swagger general API Info' is written (default: "main.go")
แปลว่า -g คือช่องบอกว่า “ไฟล์ไหนมี annotation ก้อนหัวเอกสารของหัวข้อ 6” และค่า default ของมันคือ main.go — มันจึงไปหา ./main.go ซึ่งโครงเราไม่มี

คำสั่งที่ถูกต้องคือชี้ไฟล์ให้มันดู:

$ swag init -g cmd/api/main.go
2026/08/20 22:15:53 Generate swagger docs....
2026/08/20 22:15:53 Generate general API Info, search dir:./
2026/08/20 22:15:53 warning: failed to get package name in dir: ./, ...
2026/08/20 22:15:53 Generating user.UserResponse
2026/08/20 22:15:53 Generating httputil.ErrorResponse
2026/08/20 22:15:53 Generating user.CreateUserRequest
2026/08/20 22:15:53 create docs.go at docs/docs.go
2026/08/20 22:15:53 create swagger.json at docs/swagger.json
2026/08/20 22:15:53 create swagger.yaml at docs/swagger.yaml

เรื่อง --parseDependency --parseInternal — ผลจริงต่างจากสไลด์

สไลด์ p.62 บอกว่าโครง wongnok ต้องใช้ swag init -g cmd/api/main.go --parseDependency --parseInternal ไม่งั้น “definition หายหมด” เพราะโค้ดอยู่ใน internal/
คราวนี้ผมลองแยกทีละ flag แล้วเทียบไฟล์ด้วย md5 — ผลคือ definition ไม่เคยหาย และตัวการที่ทำให้ไฟล์เปลี่ยน ไม่ใช่ flag ที่สไลด์ชี้

$ swag init -g cmd/api/main.go                                   # A
$ swag init -g cmd/api/main.go --parseInternal                    # B
$ swag init -g cmd/api/main.go --parseDependency                  # C
$ swag init -g cmd/api/main.go --parseDependency --parseInternal  # D

$ md5 -q sw_A.json sw_B.json sw_C.json sw_D.json
27d4b4c32eba7c375b7cd69a3808fce9    # A
27d4b4c32eba7c375b7cd69a3808fce9    # B ← เท่ากับ A ทุกไบต์
e7c184f840b49b6bde994728d8cb1a2e    # C
e7c184f840b49b6bde994728d8cb1a2e    # D ← เท่ากับ C ทุกไบต์

ตารางนี้บอกสองเรื่องที่สไลด์ไม่ได้บอก:

1. definition ไม่เคยหาย — แถว A ไม่ใส่ flag อะไรเลยก็ได้ครบ 3 ตัว แปลว่า swag เดินเข้า internal/ ของโปรเจกต์เราอยู่แล้วโดยค่าเริ่มต้น
2. --parseInternal ไม่ได้ทำอะไรเลยในโครงนี้ — A เท่ากับ B และ C เท่ากับ D ตัวที่เปลี่ยนชื่อ definition เป็น internal_user.* คือ --parseDependency ต่างหาก

แล้ว --parseInternal มีไว้ทำอะไรกันแน่? เปิดซอร์สของ swaggo/swag v1.16.6 ดู — ตัวแปรนี้ถูกอ่านแค่ 2 ที่:

// golist.go:51 — ในฟังก์ชัน getAllGoFileInfoFromDepsByList
ignoreInternal := pkg.Goroot && !parser.ParseInternal

// parser.go:1868 — ในฟังก์ชัน getAllGoFileInfoFromDeps
ignoreInternal := pkg.Internal && !parser.ParseInternal

สังเกตชื่อฟังก์ชัน — ทั้งคู่ลงท้ายด้วย FromDeps คือเส้นทางเดินไฟล์ของ dependency ไม่ใช่เส้นทางของโปรเจกต์เรา
คำว่า internal ตรงนี้จึงหมายถึง internal package ของ dependency และของ Go เอง (pkg.Goroot) ไม่ใช่ ./internal ที่เราสร้าง
มันจะมีความหมายก็ต่อเมื่อใส่คู่กับ --parseDependency เท่านั้น — ลำพังตัวเดียวไม่มีทางเปลี่ยนอะไรได้เลย ซึ่งตรงกับที่ md5 บอก

ส่วนโฟลเดอร์ของโปรเจกต์เราถูกเดินด้วย walkWith ที่ข้ามแค่ 4 อย่าง — ไม่มีคำว่า internal อยู่ในนั้นเลย:

// parser.go:1957
if !parseVendor && f.Name() == "vendor" ||        // vendor
    f.Name() == "docs" ||                          // docs
    len(f.Name()) > 1 && f.Name()[0] == '.' {        // โฟลเดอร์ที่ขึ้นต้นด้วยจุด
    return filepath.SkipDir
}
// + path ที่ผู้ใช้สั่ง --exclude เอง

นี่คือหลักฐานตรง ๆ ว่า ./internal ไม่เคยถูกข้าม ตั้งแต่แรก

10 · หัวใจของบท — สองกับดักที่ทำให้เอกสารกลับไปโกหกเหมือนเดิม

ถึงตรงนี้ทุกอย่างทำงานหมดแล้ว และนี่คือจุดที่คนส่วนใหญ่หยุดอ่าน
แต่สองเรื่องข้างล่างนี้ต่างหากที่ตัดสินว่าเอกสารของคุณจะเชื่อถือได้หรือไม่

กับดัก 1 — แก้ annotation แล้วลืมรัน swag init

doc.json: get /users/{id}  summary=ดึงข้อมูล User รายคน
doc.json: post /users      summary=สร้าง User ใหม่

# แก้ annotation + build ใหม่ (-count=1) แต่ยังไม่ swag init
doc.json: get /users/{id}  summary=ดึงข้อมูล User รายคน
doc.json: post /users      summary=สร้าง User ใหม่
                                    ↑ เหมือนเดิมทุกตัวอักษร ไม่มี delete โผล่มา

# รัน swag init -g cmd/api/main.go แล้ว build ใหม่
doc.json: delete /users/{id}  summary=ลบ User
doc.json: get /users/{id}     summary=ดึงข้อมูล User รายคน (แก้ข้อความแล้ว)
doc.json: post /users         summary=สร้าง User ใหม่

กับดัก 2 — ลืม @Router แล้ว endpoint หายเงียบ ๆ

// Ping godoc
//
//	@Summary	เช็คว่าเซิร์ฟเวอร์ยังอยู่
//	@Tags		health
//	@Produce	json
//	@Success	200	{object}	user.UserResponse
func (handler *Handler) Ping(ctx *gin.Context) { ... }

$ swag init -g cmd/api/main.go
2026/08/20 22:17:07 Generating user.UserResponse
2026/08/20 22:17:07 Generating httputil.ErrorResponse
2026/08/20 22:17:07 Generating user.CreateUserRequest
# ...create docs.go / swagger.json / swagger.yaml ครบตามปกติ
exit=0

paths: ['/users', '/users/{id}']
ops:   ['delete /users/{id}', 'get /users', 'get /users/{id}', 'post /users']

11 · ได้ swagger.json มาแล้ว เอาไปทำอะไรต่อได้บ้าง

ประเด็นที่หัวข้อ 2 ย้ำไว้กำลังจะออกดอกออกผลตรงนี้: swagger.json เป็นไฟล์มาตรฐาน ไม่ใช่ของเฉพาะ Go เครื่องมืออื่นในโลกจึงอ่านมันได้หมด

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

อ้างอิง

• swaggo/swag — repo · Declarative Comments Format — รายการ annotation ทั้งหมดอยู่หน้านี้หน้าเดียว ทั้ง General API Info และระดับ endpoint
• swaggo/swag — Attribute — Enums(), default(), minimum(), format() ใช้ได้กับ type ไหนบ้าง
• swaggo/gin-swagger — ที่มาของ WrapHandler และตัวอย่าง route /swagger/*any
• pkg.go.dev — swaggo/files — ไฟล์ static ของ Swagger UI ที่ทำให้หน้าเว็บเปิดได้แม้ยังไม่มี spec
• Swagger 2.0 / OpenAPI 2.0 Specification — นิยามของ key ทุกตัวใน swagger.json (paths, definitions, securityDefinitions)
• OpenAPI Initiative · openapi-generator — รายชื่อภาษาที่ generate client ได้
• Gin — param in path — ที่มาของความต่างระหว่าง :name กับ *name
• Cheat sheet Day 8 · บทเรียน 27 — project layout — เหตุผลที่ main.go ไปอยู่ cmd/api/ ตั้งแต่แรก