API Detective — จับคู่ · จับผิด · จับ annotation

คำตอบของคำถามพ่วง (ข้อ 1 กับ 2 ต่างกันตรงไหน) — ข้อ 1 ตอบคำถามว่า “ของชิ้นไหน” ส่วนข้อ 2 ตอบว่า “เอาชุดย่อยแบบไหนของของชุดนั้น”
ทดสอบง่าย ๆ: ตัดค่านั้นทิ้งแล้ว URL ยังมีความหมายอยู่ไหม
/users/ ที่ไม่มี 123 → ไม่รู้ว่าจะเอา user คนไหน = ค่านั้นต้องอยู่ใน path
/orders ที่ไม่มี ?status=paid → ยังมีความหมายอยู่ แปลว่า “เอาทั้งหมด” = ค่านั้นเป็น query

และในโค้ด Gin สองอย่างนี้ดึงด้วยคนละเมธอด — ผมยิงจริงแล้ว echo ค่าที่ดึงได้กลับมาให้ดู ว่าใครดึงด้วยอะไร:

$ curl -s 'http://127.0.0.1:18080/users/123'
{"extracted_by":"c.Param(\"id\")","id":"123","user":{...}}

$ curl -s 'http://127.0.0.1:18080/orders?status=paid'
{"extracted_by":"c.Query(\"status\")","filter_status":"paid","orders":[...]}

GET /getUser?id=123

GET /users/123

ผิดสามข้อ:

• กฎข้อ 1 (ใช้ noun ไม่ใช่ verb) — getUser เป็นกริยาเต็มตัว สไลด์บทเรียน 36 ยกตัวอย่าง GET /getUsers ไว้ในช่อง ❌ ตรง ๆ เลย
• กฎข้อ 7 (อย่าใส่ action ใน URI ถ้า method สื่อได้แล้ว) — คำว่า get ซ้ำกับ method GET ที่อยู่ข้างหน้าอยู่แล้ว พูดสองรอบเปล่า ๆ
• กฎข้อ 5 (relationship/ตัวระบุใช้ path) — 123 คือ ตัวระบุว่าเป็นของชิ้นไหน ไม่ใช่ตัวกรอง มันจึงต้องอยู่ที่ path ไม่ใช่ query (ตรงกับส่วนที่ 1 ข้อ 1 ที่เพิ่งจับคู่ไป)

และเมื่อยิงจริง สองเส้นนี้ให้ข้อมูลชุดเดียวกันเป๊ะ ต่างกันแค่ “ดึงค่าจากช่องไหน”:

=== BAD  GET /getUser?id=123 ===
{"extracted_by":"c.Query(\"id\")","id":"123","user":{"id":"123","name":"Alice"}}
HTTP 200

=== GOOD GET /users/123 ===
{"extracted_by":"c.Param(\"id\")","id":"123","user":{"id":"123","name":"Alice"}}
HTTP 200

นี่แหละคือหัวใจของทั้งส่วนนี้ — ผลลัพธ์เหมือนกัน 200 เท่ากัน ความต่างทั้งหมดอยู่ที่คนอ่านคนต่อไปเดาถูกหรือเปล่า
คนที่รู้ว่าคุณมี /users/123 จะเดา /users/456 ได้ทันที แต่คนที่เห็น /getUser?id=123 จะเดา /getOrder?id=… หรือ /getOrderById?orderId=… ดี? — เขาต้องเปิดเอกสารทุกครั้งไปตลอด

POST /deleteUser?id=123

DELETE /users/123

เรื่องที่หนักกว่า: ใช้ POST ทำงานลบ
ผิดกฎข้อ 7 ในรูปแบบที่เจ็บที่สุด — พอ POST ถูกใช้ทำทุกอย่าง (สร้างก็ POST ลบก็ POST แก้ก็ POST) method ก็ไม่เหลือความหมายอะไรเลย ทุกอย่างย้ายไปอยู่ในสตริง URI ทั้งหมด ซึ่งไม่มีเครื่องมือตัวไหนในโลกอ่านเข้าใจ
ผลตามมาที่จับต้องได้: อะไรก็ตามที่อยู่หลัง POST ไม่มีใครกล้า retry ให้คุณ ตาม RFC 9110 DELETE เป็น idempotent (ยิงซ้ำแล้วผลลัพธ์ปลายทางเท่าเดิม) ส่วน POST ไม่ใช่ — proxy · retry layer · client library จึงตัดสินใจต่างกันสิ้นเชิงเวลาเน็ตกระตุก (บทเรียน 36 หัวข้อ 6)

คำตอบของคำถามพ่วง — และมันคือคำตอบที่คนส่วนใหญ่ตอบผิด ผมยิงจริงทั้งสองแบบ ๆ ละ 3 ครั้ง:

##### GOOD: DELETE /users/123  x3 #####
call 1 -> {"deleted":"123","remaining":1}                        | HTTP 200
call 2 -> {"error":"user not found","id":"123","remaining":1}     | HTTP 404
call 3 -> {"error":"user not found","id":"123","remaining":1}     | HTTP 404

##### BAD: POST /deleteUser?id=123  x3 #####
call 1 -> {"deleted":"123","remaining":1}                        | HTTP 200
call 2 -> {"error":"user not found","id":"123","remaining":1}     | HTTP 404
call 3 -> {"error":"user not found","id":"123","remaining":1}     | HTTP 404

เหมือนกันเป๊ะ — ทั้ง status code ทั้ง body ทั้ง state ปลายทาง
ถ้าใครบอกว่า “ลองยิงซ้ำดูสิ แล้วจะเห็นความต่างเรื่อง idempotency” อันนั้นพิสูจน์ไม่ได้จริง ผมรันแล้ว
เพราะ idempotency ไม่ใช่พฤติกรรมที่ server สะท้อนออกมาเป็นตัวเลข แต่เป็น สัญญาที่ผูกกับตัว method เอง ตาม HTTP spec ซึ่ง client · proxy · ชั้น retry เอาไปใช้ตัดสินใจว่า “ยิงซ้ำได้ไหม”
พูดอีกแบบ: การเลือก DELETE แทน POST ไม่ได้เปลี่ยนสิ่งที่ server ทำ — มันเปลี่ยนสิ่งที่คนอื่นกล้าทำกับ server ของคุณ

หลุดทาง access log ของตัวเราเอง — gin.Default() มี gin.Logger() ติดมาให้ตามค่า default และ Logger ตัวนั้นพิมพ์ path พร้อม query string ทั้งก้อนลง log ทุก request

ผมยิงสองแบบติดกัน แล้ว grep หารหัสผ่านในไฟล์ log:

$ curl -X POST \
  'http://127.0.0.1:18080/createUser?name=Alice&password=123456'

$ grep -n '123456' gin-access.log
7:[GIN] 2026/08/21 - 13:01:28 | 200 | 54.083µs |
   127.0.0.1 | POST     "/createUser?name=Alice&password=123456"

$ curl -X POST 'http://127.0.0.1:18080/users' \
  -H 'Content-Type: application/json' \
  -d '{"name":"alice","password":"123456"}'

$ grep -n '123456' gin-access.log   # ไม่มีบรรทัดใหม่เพิ่ม
8:[GIN] 2026/08/21 - 13:01:28 | 201 | 195.958µs |
   127.0.0.1 | POST     "/users"

นับให้เห็นชัด ๆ ว่าทั้งไฟล์มีรหัสผ่านโผล่กี่ครั้ง:

$ grep -c '123456' gin-access.log
1

$ grep -n 'password' gin-access.log
7:[GIN] 2026/08/21 - 13:01:28 | 200 | 54.083µs |  127.0.0.1 | POST  "/createUser?name=Alice&password=123456"

เจอครั้งเดียว คือบรรทัดของ /createUser เท่านั้น — ทั้งที่ฝั่ง POST /users server ก็อ่านรหัสผ่านได้ครบเหมือนกัน (response ตอบกลับมาว่า password_len:6) แต่ body ไม่ถูก log

เส้นที่ถูก:

POST /users
Content-Type: application/json

{"name":"Alice","password":"123456"}

// server ตอบ:
HTTP 201 Created
{"created":"1000","extracted_by":"c.ShouldBindJSON (request body)","name":"alice","password_len":6}

สังเกต 201 ไม่ใช่ 200 — เส้นแบบเดิมตอบ 200 ส่วนเส้นที่ถูกตอบ 201 Created ซึ่งเป็นรหัสของ “สร้างของใหม่ขึ้นมาสำเร็จ” (บทเรียน 34) — และมันคือคำตอบของข้อ 6 ในส่วนที่ 1 พอดี

GET /getPaidOrders
GET /getPendingOrders      ← อาทิตย์หน้า
GET /getCancelledOrders    ← อาทิตย์ถัดไป
GET /getPaidOrdersThisMonth  ← แล้วก็…

GET /orders?status=paid
GET /orders?status=pending
GET /orders?status=cancelled
GET /orders?status=paid&from=2026-08-01

ผิดกฎข้อ 1 (verb) · กฎข้อ 7 (action ใน URI) · และตัวหลักคือ กฎข้อ 6 — filter ต้องใช้ query
คำว่า Paid ที่ฝังอยู่ในชื่อ endpoint คือค่าของตัวกรอง ที่ถูกจับแช่แข็งไว้ในชื่อเส้น พอค่าเปลี่ยน ชื่อเส้นก็ต้องเปลี่ยนตาม

ยิงจริงทั้งสองเส้น ได้ข้อมูลชุดเดียวกัน (ข้อมูลทดสอบมี 4 order — paid 2, pending 1, cancelled 1):

=== BAD  GET /getPaidOrders ===
{"orders":[{"id":"o1","status":"paid"},{"id":"o3","status":"paid"}]}
HTTP 200

=== GOOD GET /orders?status=paid ===
{"extracted_by":"c.Query(\"status\")","filter_status":"paid",
 "orders":[{"id":"o1","status":"paid"},{"id":"o3","status":"paid"}]}
HTTP 200

o1 กับ o3 เท่ากันทั้งสองเส้น — อีกครั้งที่ ความต่างไม่ได้อยู่ที่ผลลัพธ์วันนี้ แต่อยู่ที่ต้นทุนของวันพรุ่งนี้

เฉลย: 1→C · 2→A · 3→D · 4→F · 5→B · 6→E (ตามสไลด์ — แต่ข้อ 6 มีปัญหา อ่านต่อข้างล่าง)

ผมสร้างโปรเจกต์เล็ก ๆ ที่มี main.go ที่ root และ handler กับ httputil อยู่ใน internal/ แล้วรัน swag init จากนั้นเปิด docs/swagger.json ดูทีละจุดด้วย jq (เครื่องมือ command line สำหรับดึงค่าจาก JSON) — ว่า annotation แต่ละตัวไปโผล่ตรงไหน:

ข้อ 1 → C. @title — ไปอยู่ที่ .info.title คือระดับเอกสารทั้งไฟล์

$ jq -c '.info.title' docs/swagger.json
"Wongnok API"

ข้อ 2 → A. @Param id path string true "User ID" — แตกเป็น 5 ฟิลด์ใต้ operation นั้น

$ jq -c '.paths."/users/{id}".get.parameters' docs/swagger.json
[{"type":"string","description":"User ID","name":"id","in":"path","required":true}]

ข้อ 3 → D. @Failure 404 {object} httputil.ErrorResponse — ทำสองอย่างพร้อมกัน

$ jq -c '.paths."/users/{id}".get.responses."404"' docs/swagger.json
{"description":"Not Found","schema":{"$ref":"#/definitions/httputil.ErrorResponse"}}

$ jq -c '.definitions|keys' docs/swagger.json
["handler.User","httputil.ErrorResponse"]

คือทั้งใส่ response 404 ใต้ endpoint นั้น และสร้าง schema เข้า .definitions แล้วอ้างกลับด้วย $ref
สังเกตคำว่า "Not Found" — อันนั้น swag เติมให้เองจากเลข 404 ไม่ได้มาจากที่เราเขียน · และชื่อ key เป็นรูปแบบ แพ็กเกจ.ชื่อ struct ไม่ใช่ import path เต็ม

ข้อ 4 → F. @Security BearerAuth

$ jq -c '.paths."/users/{id}".get.security' docs/swagger.json
[{"BearerAuth":[]}]

$ jq -c '.securityDefinitions' docs/swagger.json
{"BearerAuth":{"type":"apiKey","name":"Authorization","in":"header"}}

ข้อ 5 → B. @Router /users [post] — กลายเป็น key ของ path + key ของ method

$ jq -c '.paths | to_entries | map({path:.key, methods:(.value|keys)})' docs/swagger.json
[{"path":"/users","methods":["post"]},{"path":"/users/{id}","methods":["get"]}]

คำตอบของคำถามพ่วง: ตัวเลือก E. --parseInternal คือตัวเดียวที่ไม่ใช่ annotation — อีก 5 ตัวเป็นคอมเมนต์ในไฟล์ .go ส่วนตัวนี้เป็น flag ที่พิมพ์ต่อท้ายคำสั่ง swag init ในเทอร์มินัล คนละที่กันคนละเวลากันเลย
ซึ่งพอมันเป็นของคนละชนิด มันก็เลยเป็นข้อที่ตรวจง่ายที่สุดว่าเฉลยถูกหรือเปล่า — แค่รันคำสั่งดูสองรอบก็รู้ และผมรันแล้ว…

ไม่ใส่ flag ก็สแกนครบตั้งแต่แรกแล้ว:

$ rm -rf docs && swag init -g main.go -d ./      # ไม่มี --parseInternal
2026/08/21 13:00:44 Generate swagger docs....
2026/08/21 13:00:44 Generate general API Info, search dir:./
2026/08/21 13:00:44 Generating handler.User
2026/08/21 13:00:44 Generating httputil.ErrorResponse
2026/08/21 13:00:44 create docs.go at docs/docs.go
2026/08/21 13:00:44 create swagger.json at docs/swagger.json
2026/08/21 13:00:44 create swagger.yaml at docs/swagger.yaml

handler.User กับ httputil.ErrorResponse อยู่ใน internal/ ทั้งคู่ และออกมาครบทั้ง /users และ /users/{id}

เทียบไบต์ต่อไบต์ระหว่างมี flag กับไม่มี:

$ swag init -g main.go -d ./                # ไม่ใส่ flag
$ cp docs/swagger.json run1_noflag.json
$ swag init -g main.go -d ./ --parseInternal
$ cp docs/swagger.json run2_withflag.json

$ md5 -q run1_noflag.json run2_withflag.json
fd317e5a6fe6f8a6eafea68d2a4fc7f2
fd317e5a6fe6f8a6eafea68d2a4fc7f2   # ← ค่าเดียวกันเป๊ะ

ลองครบทั้ง 4 ชุด flag บนโปรเจกต์นี้ — ไม่ใส่อะไรเลย · --parseInternal · --parseDependency · ใส่ทั้งคู่ — ได้ md5 ค่าเดียวกันหมดทั้ง 4 รอบ และ definitions เท่ากันที่ 2 ตัว (handler.User · httputil.ErrorResponse) ทุกรอบ
ทุกชุด flag ที่ผมลอง --parseInternal ไม่เคยทำให้ผลต่างเลยสักครั้ง

แล้วมันทำอะไรจริง ๆ? ไปดูซอร์สของ swaggo/swag v1.16.6 ตรง ๆ:

$ grep -rn "ParseInternal" . --include "*.go" | grep -v _test.go
golist.go:51:	ignoreInternal := pkg.Goroot && !parser.ParseInternal
parser.go:134:	// ParseInternal whether swag should parse internal packages
parser.go:135:	ParseInternal bool
parser.go:1868:	ignoreInternal := pkg.Internal && !parser.ParseInternal
cmd/swag/main.go:259:		ParseInternal:       ctx.Bool(parseInternalFlag),
gen/gen.go:114:	// ParseInternal whether swag should parse internal packages
gen/gen.go:115:	ParseInternal bool
gen/gen.go:220:	p.ParseInternal = config.ParseInternal

ได้มา 8 บรรทัด แต่ 6 บรรทัดเป็นแค่การประกาศ field และการส่งค่าต่อกันไปมา (main.go อ่านจาก flag → gen.go ส่งเข้า parser) · ที่เหลืออีก 2 บรรทัดที่ไฮไลต์ไว้ คือที่เดียวที่เอาค่านี้ไปตัดสินใจอะไรจริง ๆ:

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

ส่วนตัวที่เดินไฟล์ในโปรเจกต์เราจริง ๆ ข้ามอะไรบ้าง — อยู่ในฟังก์ชัน walkWith:

if !parseVendor && f.Name() == "vendor" ||   // ignore "vendor"
    f.Name() == "docs" ||                       // exclude docs
    len(f.Name()) > 1 && f.Name()[0] == '.' && f.Name() != ".." {
    return filepath.SkipDir
}

ข้ามแค่ vendor · docs · โฟลเดอร์ที่ขึ้นต้นด้วยจุด · และรายการใน --exclude — ไม่มีคำว่า internal อยู่ในเงื่อนไขเลย นี่คือหลักฐานตรง ๆ ว่า ./internal ไม่เคยถูกข้าม

แล้วอะไรทำให้ internal/ หายไปจากเอกสารได้จริง? คือ --exclude ต่างหาก:

$ swag init -g main.go -d ./ --exclude ./internal
$ jq -c '.paths' docs/swagger.json
{}
$ jq -c '.definitions' docs/swagger.json
null

สรุปข้อ 6: คำตอบที่ถูกคือ “ไม่ต้องใส่ flag อะไรเลย — swag สแกน internal/ ของโปรเจกต์เราให้อยู่แล้ว” · ถ้าจะจับคู่กับ flag จริง ๆ ตัวที่คุมเรื่องนี้คือ -d (ไดเรกทอรีที่ให้สแกน) และ --exclude ไม่ใช่ --parseInternal
และสาเหตุที่คนเข้าใจผิดกันหมดก็ไม่ใช่ความผิดของใคร — ข้อความใน --help ของ swag เองกำกวม มันไม่ได้บอกว่าหมายถึง internal ของ dependency