swag

Swag converts declarative Go comment annotations above your handler functions into a full Swagger 2.0 specification, then wires that spec into gin-swagger, echo-swagger, or one of a dozen other framework-specific serving middlewares. Running swag init walks your project’s Go files, extracts @Summary, @Param, @Success, and dozens of other annotation tags, resolves referenced structs into schema definitions, and writes the result as docs/docs.go, swagger.json, and swagger.yaml.

The project has powered Swagger UI integration for the Go ecosystem since 2017, with adapter packages for Gin, Echo, Fiber, Chi, net/http, and more. A companion swag fmt command normalizes existing annotation blocks in place, and a v2 branch is in active release-candidate development to add OpenAPI 3 support alongside the current Swagger 2.0 output.

What You Get

• The swag CLI (swag init, swag fmt) installed via go install github.com/swaggo/swag/cmd/swag@latest or a published Docker image
• Generated docs/docs.go, swagger.json, and swagger.yaml describing every annotated route, request/response schema, and security scheme
• A documented vocabulary of @Summary, @Param, @Success, @Failure, @Security, and dozens of other declarative comment tags
• Support for Go generics, struct composition, custom type overrides (.swaggo), and markdown-based descriptions
• Ready-made adapter packages for Gin, Echo, Fiber, Chi, net/http, Buffalo, Flamingo, Atreugo, and Hertz to serve the generated spec via Swagger UI

Common Use Cases

• Keeping OpenAPI documentation in sync with handler code by regenerating docs as a build or CI step
• Serving interactive Swagger UI for a Gin/Echo/Fiber REST API without hand-writing a YAML spec
• Standardizing request/response schema documentation across a multi-service Go backend
• Generating a machine-readable spec that downstream tools (client generators, API gateways) can consume

Under The Hood

Architecture parser.go is the core — a Parser struct that walks Go AST via go/ast and go/parser, resolves package dependencies with KyleBanks/depth and golang.org/x/tools/go/packages (parsergopackages.go, golist.go), and extracts declarative comment annotations (const.go defines the full @tag vocabulary). operation.go parses per-function @Success/@Param blocks, field_parser.go and schema.go turn struct fields into schema properties, and generics.go adds Go-generics support, all building up a go-openapi/spec.Swagger document incrementally. The gen package (gen/gen.go) takes the finished spec and renders it through pluggable genTypeWriter functions keyed by output type (go/json/yaml) using text/template. A separate format package implements swag fmt by re-parsing and rewriting comment blocks in place. cmd/swag is a thin urfave/cli/v2 flag-parsing layer over the gen package. Swapping the core AST-walking approach would ripple through nearly every top-level file, since operation.go, field_parser.go, and generics.go all consume the same package structures returned by parser.go’s dependency walker.

Tech Stack A Go 1.24 module built on go-openapi/spec for the Swagger object model, KyleBanks/depth and golang.org/x/tools/go/packages for dependency-graph resolution, urfave/cli/v2 for the CLI, sigs.k8s.io/yaml for JSON-to-YAML conversion, golang.org/x/text for property-naming-strategy case conversion, and stretchr/testify for test assertions. There is no database, network call, or web framework involved — swag is a purely static-analysis code generator, distributed via go install, a GitHub release binary, or a published Docker image. Releases are automated with GoReleaser and GitHub Actions.

Code Quality Fourteen _test.go files sit alongside their implementation counterparts (parser_test.go is larger than parser.go itself), using stretchr/testify for table-driven assertions against fixtures in testdata/. Error handling is explicit and typed throughout — parser.go and operation.go return wrapped errors via fmt.Errorf with %w rather than swallowing failures — and CI runs the test suite plus linting on every push. Naming follows standard Go conventions with doc comments on exported Parser, Operation, and Gen types, and the module targets a current Go version to exercise generics support in generics.go/generics_test.go. Coverage of the annotation-parsing logic is extensive, though integration testing relies mainly on the runnable sample projects under example/ rather than dedicated end-to-end suites.

API Design The core idea — deriving a full Swagger spec from comment annotations directly above handler functions, instead of a separate YAML/JSON file or a code-first builder API — lets Go developers keep documentation next to the code it describes and regenerate it as a build step. Ergonomics lean on a large but consistent @tag value vocabulary documented at length in the README, paired with dedicated adapter packages so the generated spec can be served with a one-line middleware call in most popular Go web frameworks. The tradeoff is a real learning curve: correctly annotating complex generic types, multi-file general-info blocks, and custom type overrides requires reading substantial documentation, and malformed annotations can fail silently or produce an incomplete spec without compiler-level feedback.