Skip to content
Get packs

Guide · Open source

How to use swag: generate Swagger 2.0 docs from Go comments

Updated · written with AI from the project's own documentation and checked against our catalogue data

swag is an open-source tool for Go developers that reads special comments (annotations) written above API handlers and produces Swagger 2.0 documentation files such as swagger.json, swagger.yaml and docs.go. This guide shows you how to install it, add annotations, generate the docs and connect them to Swagger UI so people can browse and test your API.

swagswaggo/swag · ★ 13k · MIT

Quick start

  1. 1Install swag. Run go install github.com/swaggo/swag/cmd/swag@latest. You need Go 1.19 or newer.
  2. 2Add annotations. Write swag comments above each API handler in your Go code.
  3. 3Place general info. Put general API info in main.go, or note its file path for the -g flag.
  4. 4Run swag init. Run swag init in the project root that contains main.go.
  5. 5Import the generated docs. Import the generated docs/docs.go package so your configuration is loaded.
  6. 6Serve Swagger UI. Use the plugin for your web framework to show the generated docs in Swagger UI.

Install swag

Install the swag command-line tool with Go using the package-manager route shown in the project README.

  • Requires Go 1.19 or newer if you build from source or use go install.
  • The README also mentions a Docker image and pre-compiled binaries on the release page as alternatives.
go install github.com/swaggo/swag/cmd/swag@latest

Add annotations to your API source code

swag reads comments placed above your Go API handlers. The README points to its Declarative Comments Format section for the full syntax, including General API Info and API Operation annotations.

General API info is normally written in main.go. If it lives in another file, you can tell swag where to find it with the -g flag.

  • Write annotations above each handler you want documented.
  • Put general API info in main.go, or pass its path with -g.

Generate the docs with swag init

Run swag init in the project root, the folder that contains main.go. It parses your comments and generates a docs folder with docs/docs.go, plus swagger.json and swagger.yaml by default.

Make sure to import the generated docs package so your configuration is initialised. The README shows the import line for a module named example-module-name.

  • Output goes to ./docs by default (-o changes this).
  • Default output types are go, json and yaml (--ot changes this).
swag init

Control generation with common flags

swag init has many options. The most useful ones for a first project are listed here. Run swag init -h to see the full list for your installed version.

  • -g sets the file containing general API info (default main.go).
  • -d sets the directories to parse, comma separated.
  • --exclude skips directories and files when searching.
  • -o sets the output directory and --ot sets the output types.
  • -p sets the property naming strategy: snakecase, camelcase or pascalcase (default camelcase).
  • --parseVendor and --parseDependency are disabled by default.
swag init -g http/api.go

Format your annotations (optional)

swag fmt formats swag comments. The README asks you to use the latest version of swag for this command.

swag fmt

Show the docs in Swagger UI

swag produces the documentation files; it does not serve them. The README says the generated docs can be integrated with an existing Go project using Swagger UI. It lists plugins for several frameworks, including gin, echo, net/http, gorilla/mux, go-chi/chi and fiber.

The project's Gin example, celler, shows the workflow end to end. Find it in the example/celler folder of the repository.

  • Pick the plugin that matches your framework from the Supported Web Frameworks list.
  • Follow that plugin's setup to serve Swagger UI from your generated docs.

What people use it for

  • Documenting a Gin or Echo REST API from handler comments so the docs stay next to the code.
  • Giving teammates a browsable, testable Swagger UI page for a Go service.
  • Producing swagger.json or swagger.yaml files from a Go project that needs Swagger 2.0 output.
  • Excluding internal or vendored directories from documentation with --exclude or --parseVendor settings.

Frequently asked questions

Is swag free to use?

swag is released under the MIT licence, as stated in the project README. Check the LICENSE file in the repository for the full terms.

What do I need to run swag?

You need Go 1.19 or newer if you build from source or use go install. The README also offers a Docker image and pre-compiled binaries from the release page.

Does swag support OpenAPI 3?

The README describes swag as generating Swagger 2.0 documentation. If you need OpenAPI 3.x output, the README's description suggests you should look at other tools.

Which web frameworks does swag work with?

The README lists plugins for gin, echo, buffalo, net/http, gorilla/mux, go-chi/chi, flamingo, fiber, atreugo and hertz.

Why does swag init not show my docs?

swag init only generates files. You must import the generated docs package and serve Swagger UI through your framework's plugin. The README asks you to import docs/docs.go for this reason.

How does swag compare to go-swagger or oapi-codegen?

swag generates docs from annotations written in your Go code. Other projects in the same space, such as oapi-codegen, go-swagger and kin-openapi, take different approaches; check each project's documentation to see which fits your spec format and workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

swag suits Go developers with an existing REST API who want Swagger 2.0 docs generated from code comments and shown in Swagger UI. If you need OpenAPI 3.x output, a non-Go project, or you prefer writing the API spec by hand as a separate file, pick a different tool.

Install options & downloads