Use when OpenAPI paths, methods, schemas, enums, or operationIds may have drifted from route.go, handler implementations, acceptance chains, or actual response output.
Document the API the code serves today — not what old YAML claims. The handler implementation is the truth; OpenAPI is the output.
app/handlers/endpoints/** or app/handlers/route.go.operationId duplicates or stale paths need cleanup.Don't use when:
app/handlers/route.go — endpoint families and handler wiring.resp.JsonResponse(...), resp.SetBody(...), binary writers.For each in-scope endpoint:
SetEndpoint string if params are injected by helpers)Inspect actual parsing code:
| Source | Pattern |
|---|---|
| Path param | params["name"] or helper accessor |
| Query param | req.URL.Query().Get("name") |
| Form field | req.FormValue("name") |
| JSON body | struct fields in json.Unmarshal target |
Follow the exact response-writing call:
resp.JsonResponse(payload) // → payload fields are the schema
resp.SetBody(bytes, contentType) // → binary or non-JSON response
return nil // → 200 with no body
Do not derive schema from model structs unless the handler serializes one-to-one — this is rarely true.
From the acceptance chain:
| Wire behavior | OpenAPI |
|---|---|
| Unix timestamp integer | type: integer, format: int64 |
| RFC3339 string | type: string, format: date-time |
Pointer field that becomes null | nullable: true |
Pointer field omitted via omitempty | optional (not nullable) |
| Enum | list only values from code constants, not invented |
# YAML syntax check
ruby -ryaml -e "YAML.safe_load(File.read('docs/openapi/openapi.yaml'))" 2>/dev/null || \
python3 -c "import yaml,sys; yaml.safe_load(open('docs/openapi/openapi.yaml'))"
# Duplicate operationId check
grep 'operationId:' docs/openapi/openapi.yaml | sort | uniq -d
# Build to ensure no code was broken
go build ./...
| Mistake | Fix |
|---|---|
| Copying model fields into response | Follow response-writing call site |
| Treating all pointer fields as nullable | Check omitempty behavior |
Adding {"success": true} for 200 | Document only what is actually returned |
| Keeping yaml-only fields | Remove stale YAML fields, not just add missing ones |
Taking SetEndpoint path literally | Check if helpers inject implicit path params |
| Old YAML as truth | Re-derive from current code |
Before claiming complete: