Skip to content
Get packs

swag

Generates Swagger 2.0 API docs for Go projects from code comments.

GitHub Download v2.0.0-rc6
Stars
13k
Forks
1.5k
Licence
MIT
Language
Go
Last update
1 months ago
Type
Dev tool

What it is

swag reads special comments (annotations) you write above your Go API handlers and produces Swagger 2.0 documentation files, such as swagger.json and swagger.yaml, plus a docs.go file. The generated docs can be shown in Swagger UI so people can browse and test your API. It is used to keep API documentation close to the code it describes.

  • Add annotations to Go handler functions and run swag init to generate docs
  • Serve generated docs in a Gin app using the gin-swagger plugin named in the README
  • Filter which APIs are documented with the --tags option
  • Format annotation comments with swag fmt

Great for

  • Go developers who already have a REST API using Gin, Echo, net/http, Fiber, or another listed framework
  • Teams that want Swagger UI docs generated from code comments rather than written by hand
  • Projects that need Swagger 2.0 output specifically

Not ideal for

  • Projects that need OpenAPI 3.x output, since the README describes Swagger 2.0 generation
  • Non-Go projects, since it parses Go source code
  • Teams that prefer writing the API spec by hand as a separate file
Step-by-step guide: how to use swagInstall, first run, examples, tips and FAQs
Nginx Proxy Manager vs swag

How to get it

  1. 1

    Install with a package manager

    You'll need: Go 1.19 or newer (only if building from source or using go install)

    Install swag with Go

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

    Generate docs in your project root

    swag init
  2. 2

    Run it

    • Add swag annotation comments to your API handler functions and general API info to main.go
    • Run swag init in the project root folder that contains main.go
    • Import the generated docs/docs.go package in your application
    • Serve Swagger UI using the plugin for your web framework
  3. 3

    Get the most out of it

    • Use the --tags option to include or exclude specific APIs from the docs
    • Use swag fmt to format annotation comments
    • Use --markdownFiles to pull long descriptions from markdown files
    • Use -g to point to a different file when general API info is not in main.go
    • Use the --generalInfo and --dir flags to control which files are parsed

Downloads

Source code (.zip)master branch · straight from GitHubRelease v2.0.0-rc65 files incl. checksums.txt

Strengths

  • Docs live next to the code, so they are easier to keep in sync
  • Plugins are listed for many popular Go web frameworks
  • Can be installed with go install or run through a Docker image

Trade-offs

  • Output is Swagger 2.0 only according to the README, which is older than OpenAPI 3
  • Documentation quality depends on how carefully annotations are written
  • Latest release shown is a release candidate (v2.0.0-rc6), so it may not be the most stable choice

How it compares

ProjectStarsTypeLevelUpdatedBest for
swag (this)13kDev toolintermediate1 months agoGo developers who already have a REST API using Gin, Echo, net/http, Fiber, or another listed framework
scalar16.4kAppbeginner4 days agoDevelopers who already maintain an OpenAPI or Swagger document
redoc26kLibrarybeginner5 days agoTeams that already write OpenAPI or Swagger specs and want public or internal API docs
mailpit10.8kDev toolbeginner4 days agoDevelopers testing signup, password reset, or notification emails locally
act72.5kDev toolintermediate5 days agoDevelopers who edit .github/workflows files and want faster feedback than commit-and-push cycles
pocketbase61.6kAppbeginner10 days agoDevelopers building a small web or mobile app who want a ready-made backend

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.