swag
🌍 English ∙ 简体中文 ∙ Português
![Release](https://img.shields.io/github/release/swaggo/swag.svg?style=flat-square)
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
-
Add comments to your API source code, See Declarative Comments Format.
-
Install swag by using:
go install github.com/swaggo/swag/cmd/swag@latest
To build from source you need Go (1.18 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.
- 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
- (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)
--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 delimeters 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
--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
- After using
swag init
to generate Swagger 2.0 docs, import the following packages:
import "github.com/swaggo/gin-swagger"
import "github.com/swaggo/files"
- Add General API annotations in
main.go
code:
func main() {
r := gin.Default()
c := controller.NewController()
v1 := r.Group("/api/v1")
{
accounts := v1.Group("/accounts")
{
accounts.GET(":id", c.ShowAccount)
accounts.GET("", c.ListAccounts)
accounts.POST("", c.AddAccount)
accounts.DELETE(":id", c.DeleteAccount)
accounts.PATCH(":id", c.UpdateAccount)
accounts.POST(":id/images", c.UploadAccountImage)
}
}
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8080")
}
Additionally some general API info can be set dynamically. The generated code package docs
exports SwaggerInfo
variable which we can use to set the title, description, version, host and base path programmatically. Example using Gin:
package main
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
"github.com/swaggo/gin-swagger"
"./docs"
)
func main() {
docs.SwaggerInfo.Title = "Swagger Example API"
docs.SwaggerInfo.Description = "This is a sample server Petstore server."
docs.SwaggerInfo.Version = "1.0"
docs.SwaggerInfo.Host = "petstore.swagger.io"
docs.SwaggerInfo.BasePath = "/v2"
docs.SwaggerInfo.Schemes = []string{"http", "https"}
r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run()
}
- Add API Operation annotations in
controller
code
package controller
import (
"fmt"
"net/http"
"strconv"
"github.com/gin-gonic/gin"
"github.com/swaggo/swag/example/celler/httputil"
"github.com/swaggo/swag/example/celler/model"
)
func (c *Controller) ShowAccount(ctx *gin.Context) {
id := ctx.Param("id")
aid, err := strconv.Atoi(id)
if err != nil {
httputil.NewError(ctx, http.StatusBadRequest, err)
return
}
account, err := model.AccountOne(aid)
if err != nil {
httputil.NewError(ctx, http.StatusNotFound, err)
return
}
ctx.JSON(http.StatusOK, account)
}
func (c *Controller) ListAccounts(ctx *gin.Context) {
q := ctx.Request.URL.Query().Get("q")
accounts, err := model.AccountsAll(q)
if err != nil {
httputil.NewError(ctx, http.StatusNotFound, err)
return
}
ctx.JSON(http.StatusOK, accounts)
}
swag init
- Run your app, and browse to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as shown below:
![swagger_index.html](https://raw.githubusercontent.com/swaggo/swag/master/assets/swagger-image.png)
The swag formatter
The Swag Comments can be automatically formatted, just like 'go fmt'.
Find the result of formatting here.
Usage:
swag fmt
Exclude folder:
swag fmt -d ./ --exclude ./internal
When using swag fmt
, you need to ensure that you have a doc comment for the function to ensure correct formatting.
This is due to swag fmt
indenting swag comments with tabs, which is only allowed after a standard doc comment.
For example, use
func (c *Controller) ListAccounts(ctx *gin.Context) {
Implementation Status
Swagger 2.0 document
General API Info
Example
celler/main.go
annotation | description | example |
---|
title | Required. The title of the application. | // @title Swagger Example API |
version | Required. Provides the version of the application API. | // @version 1.0 |
description | A short description of the application. | // @description This is a sample server celler server. |
tag.name | Name of a tag. | // @tag.name This is the name of the tag |
tag.description | Description of the tag | // @tag.description Cool Description |
tag.docs.url | Url of the external Documentation of the tag | // @tag.docs.url https://example.com |
tag.docs.description | Description of the external Documentation of the tag | // @tag.docs.description Best example documentation |
termsOfService | The Terms of Service for the API. | // @termsOfService http://swagger.io/terms/ |
contact.name | The contact information for the exposed API. | // @contact.name API Support |
contact.url | The URL pointing to the contact information. MUST be in the format of a URL. | // @contact.url http://www.swagger.io/support |
contact.email | The email address of the contact person/organization. MUST be in the format of an email address. | // @contact.email support@swagger.io |
license.name | Required. The license name used for the API. | // @license.name Apache 2.0 |
license.url | A URL to the license used for the API. MUST be in the format of a URL. | // @license.url http://www.apache.org/licenses/LICENSE-2.0.html |
host | The host (name or ip) serving the API. | // @host localhost:8080 |
BasePath | The base path on which the API is served. | // @BasePath /api/v1 |
accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types. | // @accept json |
produce | A list of MIME types the APIs can produce. Value MUST be as described under Mime Types. | // @produce json |
query.collection.format | The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default. | // @query.collection.format multi |
schemes | The transfer protocol for the operation that separated by spaces. | // @schemes http https |
externalDocs.description | Description of the external document. | // @externalDocs.description OpenAPI |
externalDocs.url | URL of the external document. | // @externalDocs.url https://swagger.io/resources/open-api/ |
x-name | The extension key, must be start by x- and take only json value | // @x-example-key {"key": "value"} |
Using markdown descriptions
When a short string in your documentation is insufficient, or you need images, code examples and things like that you may want to use markdown descriptions. In order to use markdown descriptions use the following annotations.
annotation | description | example |
---|
title | Required. The title of the application. | // @title Swagger Example API |
version | Required. Provides the version of the application API. | // @version 1.0 |
description.markdown | A short description of the application. Parsed from the api.md file. This is an alternative to @description | // @description.markdown No value needed, this parses the description from api.md |
tag.name | Name of a tag. | // @tag.name This is the name of the tag |
tag.description.markdown | Description of the tag this is an alternative to tag.description. The description will be read from a file named like tagname.md | // @tag.description.markdown |
API Operation
Example
celler/controller
annotation | description |
---|
description | A verbose explanation of the operation behavior. |
description.markdown | A short description of the application. The description will be read from a file. E.g. @description.markdown details will load details.md |
id | A unique string used to identify the operation. Must be unique among all API operations. |
tags | A list of tags to each API operation that separated by commas. |
summary | A short summary of what the operation does. |
accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types. |
produce | A list of MIME types the APIs can produce. Value MUST be as described under Mime Types. |
param | Parameters that separated by spaces. param name ,param type ,data type ,is mandatory? ,comment attribute(optional) |
security | Security to each API operation. |
success | Success response that separated by spaces. return code or default ,{param type} ,data type ,comment |
failure | Failure response that separated by spaces. return code or default ,{param type} ,data type ,comment |
response | As same as success and failure |
header | Header in response that separated by spaces. return code ,{param type} ,data type ,comment |
router | Path definition that separated by spaces. path ,[httpMethod] |
deprecatedrouter | As same as router, but deprecated. |
x-name | The extension key, must be start by x- and take only json value. |
x-codeSample | Optional Markdown usage. take file as parameter. This will then search for a file named like the summary in the given folder. |
deprecated | Mark endpoint as deprecated. |
Mime Types
swag
accepts all MIME Types which are in the correct format, that is, match */*
.
Besides that, swag
also accepts aliases for some MIME Types as follows:
Alias | MIME Type |
---|
json | application/json |
xml | text/xml |
plain | text/plain |
html | text/html |
mpfd | multipart/form-data |
x-www-form-urlencoded | application/x-www-form-urlencoded |
json-api | application/vnd.api+json |
json-stream | application/x-json-stream |
octet-stream | application/octet-stream |
png | image/png |
jpeg | image/jpeg |
gif | image/gif |
Param Type
- query
- path
- header
- body
- formData
Data Type
- string (string)
- integer (int, uint, uint32, uint64)
- number (float32)
- boolean (bool)
- file (param data type when uploading)
- user defined struct
Security
annotation | description | parameters | example |
---|
securitydefinitions.basic | Basic auth. | | // @securityDefinitions.basic BasicAuth |
securitydefinitions.apikey | API key auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth |
securitydefinitions.oauth2.application | OAuth2 application auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application |
securitydefinitions.oauth2.implicit | OAuth2 implicit auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
securitydefinitions.oauth2.password | OAuth2 password auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password |
securitydefinitions.oauth2.accessCode | OAuth2 access code auth. | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode |
Attribute
It also works for the struct fields:
type Foo struct {
Bar string `minLength:"4" maxLength:"16" example:"random string"`
Baz int `minimum:"10" maximum:"20" default:"15"`
Qux []string `enums:"foo,bar,baz"`
}
Available
Future
Examples
Descriptions over multiple lines
You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:
User defined structure with an array type
package model
type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
}
Function scoped struct declaration
You can declare your request response structs inside a function body.
You must have to follow the naming convention <package-name>.<function-name>.<struct-name>
.
package main
func MyHandler() {
type request struct {
RequestField string
}
type response struct {
ResponseField string
}
}
Model composition in response
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
type JSONResult struct {
Code int `json:"code" `
Message string `json:"message"`
Data interface{} `json:"data"`
}
type Order struct {
Id uint `json:"id"`
Data interface{} `json:"data"`
}
- also support array of objects and primitive types as nested response
@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
@success 200 {object} jsonresult.JSONResult{data=string} "desc"
@success 200 {object} jsonresult.JSONResult{data=[]string} "desc"
- overriding multiple fields. field will be added if not exists
@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
- overriding deep-level fields
type DeepObject struct {
...
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"
Use multiple path params
Add multiple paths
Example value of struct
type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
}
SchemaExample of body
Description of struct
type Account struct {
ID int `json:"id"`
Name string `json:"name"`
}
#708 The parser handles only struct comments starting with @Description
attribute.
But it writes all struct field comments as is.
So, generated swagger doc as follows:
"Account": {
"type":"object",
"description": "User account information with user id and username"
"properties": {
"id": {
"type": "integer",
"description": "ID this is userid"
},
"name": {
"type":"string",
"description": "This is Name"
}
}
}
Use swaggertype tag to supported custom type
#201
type TimestampTime struct {
time.Time
}
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
bin := make([]byte, 16)
bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
return bin, nil
}
func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
v, err := strconv.ParseInt(string(bin), 10, 64)
if err != nil {
return err
}
t.Time = time.Unix(v, 0)
return nil
}
type Account struct {
ID sql.NullInt64 `json:"id" swaggertype:"integer"`
RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}
#379
type CerticateKeyPair struct {
Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}
generated swagger doc as follows:
"api.MyBinding": {
"type":"object",
"properties":{
"crt":{
"type":"string",
"format":"base64",
"example":"U3dhZ2dlciByb2Nrcw=="
},
"key":{
"type":"string",
"format":"base64",
"example":"U3dhZ2dlciByb2Nrcw=="
}
}
}
Use global overrides to support a custom type
If you are using generated files, the swaggertype
or swaggerignore
tags may not be possible.
By passing a mapping to swag with --overridesFile
you can tell swag to use one type in place of another wherever it appears. By default, if a .swaggo
file is present in the current directory it will be used.
Go code:
type MyStruct struct {
ID sql.NullInt64 `json:"id"`
Name sql.NullString `json:"name"`
}
.swaggo
:
// Replace all NullInt64 with int
replace database/sql.NullInt64 int
// Don't include any fields of type database/sql.NullString in the swagger docs
skip database/sql.NullString
Possible directives are comments (beginning with //
), replace path/to/a.type path/to/b.type
, and skip path/to/a.type
.
(Note that the full paths to any named types must be provided to prevent problems when multiple packages define a type with the same name)
Rendered:
"types.MyStruct": {
"id": "integer"
}
Use swaggerignore tag to exclude a field
type Account struct {
ID string `json:"id"`
Name string `json:"name"`
Ignored int `swaggerignore:"true"`
}
Add extension info to struct field
type Account struct {
ID string `json:"id" extensions:"x-nullable,x-abc=def,!x-omitempty"`
}
generate swagger doc as follows:
"Account": {
"type": "object",
"properties": {
"id": {
"type": "string",
"x-nullable": true,
"x-abc": "def",
"x-omitempty": false
}
}
}
Rename model to display
type Resp struct {
Code int
}
How to use security annotations
General API info.
Each API operation.
Make it AND condition
Make it OR condition
Add a description for enum items
type Example struct {
Order string `enums:"asc,desc"`
}
Generate only specific docs file types
By default swag
command generates Swagger specification in three different files/file types:
- docs.go
- swagger.json
- swagger.yaml
If you would like to limit a set of file types which should be generated you can use --outputTypes
(short -ot
) flag. Default value is go,json,yaml
- output types separated with comma. To limit output only to go
and yaml
files, you would write go,yaml
. With complete command that would be swag init --outputTypes go,yaml
.
How to use Generics
func GetPosts(w http.ResponseWriter, r *http.Request) {
_ = web.GenericNestedResponse[types.Post]{}
}
See this file for more details
and other examples.
Change the default Go Template action delimiters
#980
#1177
If your swagger annotations or struct fields contain "{{" or "}}", the template generation will most likely fail, as these are the default delimiters for go templates.
To make the generation work properly, you can change the default delimiters with -td
. For example:
swag init -g http/api.go -td "[[,]]"
The new delimiter is a string with the format "<left delimiter>
,<right delimiter>
".
About the Project
This project was inspired by yvasiyarov/swagger but we simplified the usage and added support a variety of web frameworks. Gopher image source is tenntenn/gopher-stickers. It has licenses creative commons licensing.
Contributors
This project exists thanks to all the people who contribute. [Contribute].
![](https://opencollective.com/swag/contributors.svg?width=890&button=false)
Backers
Thank you to all our backers! 🙏 [Become a backer]
![](https://opencollective.com/swag/backers.svg?width=890)
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
![](https://opencollective.com/swag/sponsor/9/avatar.svg)
License
![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fswaggo%2Fswag.svg?type=large)