Make the generated docs/openapi/gateway.yaml usable by adding three things
go-doc parses out of the .api source:
- @server tags + summary on every block → Swagger UI groups endpoints
(Auth / Member / Permission / Normal) instead of dumping everything
under "default".
- backtick end-of-line // 中文 on every Request field → property
descriptions in the schema. go-doc only reads the trailing comment,
not the line above, so all comments are placed on the same line as
the tag.
- options=A|B|C in json/form tags wherever validate:"oneof=..." exists
→ enum dropdowns. The validate tag is kept for runtime validation;
go-zero also enforces options= at bind time.
Codify the rules in generate/api/README.md (tags / 行末註解 / options=)
and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex)
picks them up automatically when working on the project.
types.go regenerated via make gen-api to keep json tags in sync.
Co-authored-by: Cursor <cursoragent@cursor.com>
王性驊
王性驊