swag

swag is a command-line tool for Go developers that reads special annotation comments in your source code and automatically generates API documentation in the Swagger 2.0 format. Swagger is a widely used standard for describing what an HTTP API does: which endpoints exist, what parameters they accept, what data they return, and how authentication works. Swagger documentation can be served as an interactive web panel where other developers can browse and test your API without writing any code themselves. Rather than maintaining this specification in a separate file, swag lets you keep the descriptions alongside your code and regenerate the docs as the codebase changes.

The basic workflow is: add structured comments above your API handler functions using a format swag recognizes, then run swag init from your project root. This command parses your Go files, finds the annotations, and produces a docs/ folder containing a docs.go file plus JSON and YAML versions of the API specification. You import that generated file into your project so a Swagger UI panel can serve the documentation in a browser.

swag supports a range of annotation types. You can document general API info (title, version, contact, license, base URL), individual operations (route, HTTP method, parameters, request body, response codes and types), and security schemes like API keys or OAuth. Complex Go types, arrays, generics, nested structs, and embedded types are all handled.

Plugins connect swag to popular Go web frameworks including Gin, Echo, Fiber, and others, so the generated documentation wires into the framework's routing with minimal setup. A separate swag fmt command formats your annotation comments consistently, the same way gofmt standardizes Go code across a team.

The full README is longer than what was shown.