go-swagger

# Go Swagger / OpenAPI with swaggo `github.com/swaggo/swag` is the de-facto annotation-driven OpenAPI generator for Go. You annotate handlers with `// @...` comments, run the `swag` CLI, and get `docs/swagger.json`, `docs/swagger.yaml`, and `docs/docs.go` for the UI. ## Core Rules 1. **Docs are a contract.** A field documented as required is the API's promise; a mismatch with the implementation is a bug. 2. **Annotations live next to handlers.** Not in a separate `docs/` folder — comments rot when separated from code. 3. **Regenerate on every change.** `swag init` is part of the build (`go generate` or a Makefile target). Stale `docs/` is worse than no docs. 4. **The `docs` package must be imported.** A blank import (`_ "yourmod/docs"`) registers the spec at process start. 5. **Use named structs for request/response bodies.** swag cannot derive a schema from `map[string]any` or a primitive type. 6. **Security definitions match implementation.** If the API enforces JWT, declare `@securityDefinitions.apikey Bearer` and annotate every protected endpoint with `@Security Bearer`. ## Install and Bootstrap ```bash go install github.com/swaggo/swag/cmd/swag@latest swag init # general info from main.go swag init -g cmd/api/main.go # custom main path swag fmt # format annotation comments like gofmt ``` Wire the UI for your framework — choose one: ```go // Gin import ( swaggerFiles "github.com/swaggo/files" ...