[opensourcedex]

swag is a free, open source api development & testing project written in Go and released under MIT. It has 13,024 GitHub stars, 1,547 forks and 476 open issues, and was last pushed 5 days ago. On this registry it ranks #16 of 103 tracked projects in API Development & Testing, with 5 head-to-head comparisons available. It gained 4 stars over the last 3 tracked days.

What is swag?

What it is

Swag is a command-line tool that converts Go source annotations into Swagger 2.0 documentation. It lives in the Go ecosystem, is distributed under the MIT license, and is maintained by the swaggo organization. The project has been active for nine years, with the most recent push recorded in September 2026, and it carries roughly 13,000 stars and 1,545 forks on GitHub.

The concrete problem it solves is the drift between a Go HTTP API and its documentation. Instead of maintaining a separate specification file by hand, a developer writes declarative comments next to the handlers and structs that already exist, then runs the generator to produce the specification and the Go file that serves it. Swag also ships plugins for popular Go web frameworks, so the generated documentation can be wired into an existing project and viewed through Swagger UI without restructuring the application.

Key capabilities

  • Converts declarative Go comments into a Swagger 2.0 specification, covering general API info and per-operation details.
  • Generates a docs folder and a docs/docs.go file that the application imports so its configuration is initialized at startup.
  • Supports security annotations for describing authentication schemes on operations.
  • Handles Go generic types in generated schemas.
  • Provides the swaggertype tag for custom types and global overrides for types that appear throughout a codebase.
  • Provides the swaggerignore tag to exclude a struct field from the generated schema.
  • Supports request headers, response headers, multiple path parameters, example values for structs, schema examples for request bodies, model composition in responses, function-scoped struct declarations, renamed models, enum item descriptions, extension info on struct fields, and generation limited to specific documentation file types.

Who uses it and how

  • Go teams annotate existing handlers and structs, then run swag init in the project root to produce documentation without writing a separate specification.
  • Projects whose general API annotations do not live in main.go point the generator at the correct file with the -g flag, for example swag init -g http/api.go.
  • Applications import the generated package with a blank import such as import _ "example-module-name/docs" so the documentation configuration is registered.
  • Developers integrating with a Go web framework use the framework-specific plugins to serve the generated specification alongside Swagger UI.
  • Teams that want consistent comment layout run swag fmt to format the annotation blocks.

Getting started

Install with go install github.com/swaggo/swag/cmd/swag@latest, which requires Go 1.19 or newer when building from source. Alternatively run the container with docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest, or download a pre-compiled binary from the release page, then run swag init in the folder containing main.go.

When to use it — and when not to

Swag fits Go projects that want documentation generated from the code they already maintain, and it avoids the manual synchronization that a hand-written specification requires. A self-hoster operates only the generator and the application that serves the output; the tool itself introduces

project readme (upstream, from github) — read inline

swag

🌍 English ∙ 简体中文 ∙ Português

Build Status Coverage Status Go Report Card Go Doc Backers on Open Collective Sponsors on Open Collective FOSSA Status Release

Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).

Contents

Getting started

  1. Add comments to your API source code, See Declarative Comments Format.

  2. Install swag by using:

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

To build from source you need Go (1.19 or newer).

Alternatively you can run the docker image:

docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest

Or download a pre-compiled binary from the release page.

  1. Run swag init in the project's root folder which contains the main.go file. This will parse your comments and generate the required files (docs folder and docs/docs.go).
swag init

Make sure to import the generated docs/docs.go so that your specific configuration gets init'ed. If your General API annotations do not live in main.go, you can let swag know with -g flag.

import _ "example-module-name/docs"

swag init -g http/api.go
  1. (optional) Use swag fmt format the SWAG comment. (Please upgrade to the latest version)
swag fmt

swag cli

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --quiet, -q                            Make the logger quiet. (default: false)
   --generalInfo value, -g value          Go file path in which 'swagger general API Info' is written (default: "main.go")
   --dir value, -d value                  Directories you want to parse,comma separated and general-info file must be in the first one (default: "./")
   --exclude value                        Exclude directories and files when searching, comma separated
   --propertyStrategy value, -p value     Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
   --output value, -o value               Output directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: "./docs")
   --outputTypes value, --ot value        Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: "go,json,yaml")
   --parseVendor                          Parse go files in 'vendor' folder, disabled by default (default: false)
   --parseDependency, --pd                Parse go files inside dependency folder, disabled by default (default: false)
   --parseDependencyLevel, --pdl          Enhancement of '--parseDependency', parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)
   --markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default
   --codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
   --parseInternal                        Parse go files in internal packages, disabled by default (default: false)
   --generatedTime                        Generate timestamp at the top of docs.go, disabled by default (default: false)
   --parseDepth value                     Dependency parse depth (default: 100)
   --requiredByDefault                    Set validation required for all fields by default (default: false)
   --instanceName value                   This parameter can be used to name different swagger document instances. It is optional.
   --overridesFile value                  File to read global type overrides from. (default: ".swaggo")
   --parseGoList                          Parse dependency via 'go list' (default: true)
   --tags value, -t value                 A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded
   --templateDelims value, --td value     Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
   --collectionFormat value, --cf value   Set default collection format (default: "csv")
   --state value                          Initial state for the state machine (default: ""), @HostState in root file, @State in other files
   --parseFuncBody                        Parse API info within body of functions in go files, disabled by default (default: false)
   --help, -h                             show help (default: false)

swag fmt -h
NAME:
   swag fmt - format swag comments

USAGE:
   swag fmt [command options] [arguments...]

OPTIONS:
   --dir value, -d value          Directories you want to parse,comma separated and general-info file must be in the first one (default: "./")
   --exclude value                Exclude directories and files when searching, comma separated
   --generalInfo value, -g value  Go file path in which 'swagger general API Info' is written (default: "main.go")
   --help, -h                     show help (default: false)

Supported Web Frameworks

How to use it with Gin

Find the example source code here.

Finish the steps in Getting started

  1. After using swag init to generate Swagger

readme truncated — read the full docs on github

Frequently asked questions

Is swag free to use?

swag is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does swag do?

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

What is swag written in?

swag is primarily written in Go. Its source is publicly available at https://github.com/swaggo/swag, and it has 13,024 GitHub stars.