golang-swaggerlisted

# Swaggo API Documentation Treat the generated specification as a consumer contract derived from annotations and code. Preserve the project's generator version, framework integration, output location, and ownership rules. ## Inspect the existing toolchain Before editing: 1. Read go.mod, generator pinning, go:generate or build commands, API entry point, router registration, annotations, generated files, and CI drift checks. 2. Determine which files are sources and which are generated. 3. Confirm the target Swagger or OpenAPI dialect and the installed swaggo version from project evidence. 4. Identify public versus internal routes and whether documentation UI is enabled in each environment. 5. Check the repository's error envelope, authentication schemes, naming, tags, and compatibility policy. Do not replace a spec-first workflow or hand-edit generated output. If the project has no chosen documentation tool, compare approaches before adding swaggo. Read [annotation recipes](references/annotation-recipes.md) when writing `@Param`, `@Success`, `@Failure`, `@Router`, `@Security`, general metadata, or model tags. Adapt the examples to the pinned generator rather than treating them as a complete grammar. ## Document the real contract For each operation, reconcile annotations with router and handler behavior: - HTTP method and exact path; - path, query, header, form, and body parameters; - requiredness, defaults, ranges, enums, formats, and collection behavior; - request and