Repolode
Submit
swaggo

swaggo/swag

Go tool that generates Swagger 2.0 API documentation from annotations written in your Go source code comments.

View on GitHub
Stars
13,047
Forks
1,492
Open issues
482
Last commit
last month

What is it?

Swag parses specially formatted comments in Go code, such as handler functions and struct definitions, and produces Swagger 2.0 documentation as swagger.json, swagger.yaml and a docs.go file. Developers add annotations like @Summary, @Param, @Success and @Router above their handlers, and run swag init to regenerate the spec.

The generated output can be served through Swagger UI using middleware packages for popular Go web frameworks, including Gin, Echo, Fiber, net/http, chi and Hertz. Struct fields can be annotated with tags for examples, validation constraints, enums and overrides for custom types. Swag also includes a swag fmt command that formats the annotation comments.

Key features

  • 01Generates Swagger 2.0 specs as JSON, YAML and a Go docs package.
  • 02Documents endpoints through comment annotations placed above Go handler functions.
  • 03Supports request parameters, responses, headers, security definitions and tags.
  • 04Reads struct field tags for examples, validation rules and enums.
  • 05Provides middleware for Gin, Echo, Fiber, net/http, chi and other frameworks.
  • 06Includes a swag fmt command to format annotation comments.

Use cases

  • Generating API documentation for a Go REST service without maintaining a separate OpenAPI file by hand.
  • Exposing an interactive Swagger UI page for a Gin or Echo backend.
  • Keeping API docs in sync with handler code during CI builds.

Quick start

  1. 1

    Install the swag CLI with Go

    go install github.com/swaggo/swag/cmd/swag@latest
  2. 2

    Add API annotations to your Go source comments

  3. 3

    Run swag init in the project root containing main.go to generate docs

    swag init

Things to know

  • Generates Swagger 2.0 documentation only, not OpenAPI 3.x.
  • Requires writing annotations in Go comments and regenerating docs after changes.

Topics

#golang#swagger#openapi#api-documentation#rest-api#code-generation#annotations#swagger2

FAQ

What is swag?
Go tool that generates Swagger 2.0 API documentation from annotations written in your Go source code comments. Swag parses specially formatted comments in Go code, such as handler functions and struct definitions, and produces Swagger 2.0 documentation as swagger.json, swagger.yaml and a docs.go file. Developers add annotations like @Summary, @Param, @Success and @Router above their handlers, and run swag init to regenerate the spec.
Is swag free to use? What license does it have?
swag is open source under the MIT license. Check the license terms before using it in commercial products.
Is swag still maintained?
Updated within 6 months. The last commit to swag was on Sep 30, 2026.
What can I use swag for?
Generating API documentation for a Go REST service without maintaining a separate OpenAPI file by hand. Exposing an interactive Swagger UI page for a Gin or Echo backend. Keeping API docs in sync with handler code during CI builds.
How do I install swag?
Install the swag CLI with Go: go install github.com/swaggo/swag/cmd/swag@latest Add API annotations to your Go source comments Run swag init in the project root containing main.go to generate docs: swag init
Where can I get swag?
The source code and installation instructions are on GitHub: https://github.com/swaggo/swag

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects