swag Documentation

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

12,862 stars Go Go 1 file · ~28,412 tokens #annotations#golang#openapi#swagger#swagger2
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy swag on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name swag --restart always swaggo/swag:latest

File: README.md

swag

🌍 English ∙ 简体中文 ∙ Português







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:

sh
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:

sh
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).
sh
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.

go
import _ "example-module-name/docs"
sh
swag init -g http/api.go
  1. (optional) Use swag fmt format the SWAG comment. (Please upgrade to the latest version)
sh
swag fmt

swag cli

text
/* Detailed source-code truncated for AI context efficiency. */
bash
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 2.0 docs, import the following packages:
go
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
  1. Add General API annotations in main.go code:
go
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
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:

go
package main

import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	"github.com/swaggo/gin-swagger"

	"./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

	// programmatically set swagger info
	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()

	// use ginSwagger middleware to serve the API docs
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	r.Run()
}
  1. Add API Operation annotations in controller code
go
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"
)

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
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)
}

// ListAccounts godoc
// @Summary      List accounts
// @Description  get accounts
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        q    query     string  false  "name search by q"  Format(email)
// @Success      200  {array}   model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts [get]
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)
}
//...
console
swag init
  1. Run your app, and browse to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as shown below:

The swag formatter

The Swag Comments can be automatically formatted, just like 'go fmt'.
Find the result of formatting here.

Usage:

shell
swag fmt

Exclude folder：

shell
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

go
// ListAccounts lists all existing accounts
//
//  @Summary      List accounts
//  @Description  get accounts
//  @Tags         accounts
//  @Accept       json
//  @Produce      json
//  @Param        q    query     string  false  "name search by q"  Format(email)
//  @Success      200  {array}   model.Account
//  @Failure      400  {object}  httputil.HTTPError
//  @Failure      404  {object}  httputil.HTTPError
//  @Failure      500  {object}  httputil.HTTPError
//  @Router       /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {

Implementation Status

Swagger 2.0 document

  • Basic Structure
  • API Host and Base Path
  • Paths and Operations
  • Describing Parameters
  • Describing Request Body
  • Describing Responses
  • MIME Types
  • Authentication
    • Basic Authentication
    • API Keys
  • Adding Examples
  • File Upload
  • Enums
  • Grouping Operations With Tags
  • Swagger Extensions

Declarative Comments Format

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 [email protected]
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
tag.x-name The extension key, must be start by x- and take only string value // @x-example-key value

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
event-stream text/event-stream

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
parameters annotation example
in // @in header
name // @name Authorization
tokenUrl // @tokenUrl https://example.com/oauth/token
authorizationurl // @authorizationurl https://example.com/oauth/authorize
scope.hoge // @scope.write Grants write access
description // @description OAuth protects our entity endpoints

Attribute

go
// @Param   enumstring  query     string     false  "string enums"       Enums(A, B, C)
// @Param   enumint     query     int        false  "int enums"          Enums(1, 2, 3)
// @Param   enumnumber  query     number     false  "int enums"          Enums(1.1, 1.2, 1.3)
// @Param   string      query     string     false  "string valid"       minlength(5)  maxlength(10)
// @Param   int         query     int        false  "int valid"          minimum(1)    maximum(10)
// @Param   default     query     string     false  "string default"     default(A)
// @Param   example     query     string     false  "string example"     example(string)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

It also works for the struct fields:

go
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

Field Name Type Description
validate string Determines the validation for the parameter. Possible values are: required,optional.
json string JSON tag options. The omitempty option will mark the field as not required.
default * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter.
maximum number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
multipleOf number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
maxLength integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums [*] See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
format string The extending format for the previously mentioned type. See Data Type Formats for further details.
collectionFormat string Determines the format of the array if type array is used. Possible values are:
  • csv - comma separated values foo,bar.
  • ssv - space separated values foo bar.
  • tsv - tab separated values foo\tbar.
  • pipes - pipe separated values foo|bar.
  • multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData". Default value is csv.
    		•
    example * Declares the example for the parameter value
    extensions string Add extension to parameters.

    Future

    Field Name Type Description
    pattern string See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
    maxItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
    minItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
    uniqueItems boolean See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.

    Examples

    Descriptions over multiple lines

    You can add descriptions spanning multiple lines in either the general api description or routes definitions like so:

    go
    // @description This is the first line
// @description This is the second line
// @description And so forth.

    User defined structure with an array type

    go
    // @Success 200 {array} model.Account <-- This is a user defined struct.
    go
    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 .<function-name>.<struct-name> .

    go
    package main

// @Param request body main.MyHandler.request true "query params"
// @Success 200 {object} main.MyHandler.response
// @Router /test [post]
func MyHandler() {
	type request struct {
		RequestField string
	}

	type response struct {
		ResponseField string
	}
}

    Model composition in response

    go
    // JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
    go
    type JSONResult struct {
    Code    int          `json:"code" `
    Message string       `json:"message"`
    Data    interface{}  `json:"data"`
}

type Order struct { //in `proto` package
    Id  uint            `json:"id"`
    Data  interface{}   `json:"data"`
}
    • also support array of objects and primitive types as nested response
    go
    @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
    go
    @success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
    • overriding deep-level fields
    go
    type DeepObject struct { //in `proto` package
	...
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"

    Add request headers

    go
    // @Param        X-MyHeader	  header    string    true   	"MyHeader must be set for valid response"
// @Param        X-API-VERSION    header    string    true   	"API version eg.: 1.0"

    Add response headers

    go
    // @Success      200              {string}  string    "ok"
// @failure      400              {string}  string    "error"
// @response     default          {string}  string    "other error"
// @Header       200              {string}  Location  "/entity/1"
// @Header       200,400,default  {string}  Token     "token"
// @Header       all              {string}  Token2    "token2"

    Use multiple path params

    go
    /// ...
// @Param group_id   path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

    Add multiple paths

    go
    /// ...
// @Param group_id path int true "Group ID"
// @Param user_id  path int true "User ID"
// ...
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
// @Router /examples/user/{user_id}/address [put]

    Example value of struct

    go
    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

    go
    // @Param email body string true "message/rfc822" SchemaExample(Subject: Testmail\r\n\r\nBody Message\r\n)

    Description of struct

    go
    // Account model info
// @Description User account information
// @Description with user id and username
type Account struct {
	// ID this is userid
	ID   int    `json:"id"`
	Name string `json:"name"` // This is 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:

    json
    "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

    go
    type TimestampTime struct {
    time.Time
}

///implement encoding.JSON.Marshaler interface
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 {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

    // Array types can be overridden using "array," format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

    #379

    go
    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:

    go
    "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:

    go
    type MyStruct struct {
  ID     sql.NullInt64 `json:"id"`
  Name   sql.NullString `json:"name"`
}

    .swaggo:

    text
    // 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:

    go
    "types.MyStruct": {
  "id": "integer"
}

    Use swaggerignore tag to exclude a field

    go
    type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}

    Add extension info to struct field

    go
    type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}

    generate swagger doc as follows:

    go
    "Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def",
            "x-omitempty": false
        }
    }
}

    Rename model to display

    golang
    type Resp struct {
	Code int
}//@name Response

    How to use security annotations

    General API info.

    go
    // @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

    Each API operation.

    go
    // @Security ApiKeyAuth

    Make it OR condition

    go
    // @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

    Make it AND condition

    go
    // @Security ApiKeyAuth && firebase
// @Security OAuth2Application[write, admin] && APIKeyAuth

    Generate enum types from enum constants

    You can generate enums from ordered constants. Each enum variant can have a comment, an override name, or both. This works with both iota-defined and manually defined constants.

    go
    type Difficulty string

const (
	Easy   Difficulty = "easy" // You can add a comment to the enum variant.
	Medium Difficulty = "medium" // @name MediumDifficulty
	Hard   Difficulty = "hard" // @name HardDifficulty You can have a name override and a comment.
)

type Class int

const (
	First Class = iota // @name FirstClass
	Second // Name override and comment rules apply here just as above.
	Third // @name ThirdClass This one has a name override and a comment.
)

// There is no need to add `enums:"..."` to the fields, it is automatically generated from the ordered consts.
type Quiz struct {
	Difficulty Difficulty
	Class Class
	Questions []string
	Answers []string
}

    Add a description for enum items

    go
    type Example struct {
	// Sort order:
	// * asc - Ascending, from A to Z.
	// * desc - Descending, from Z to A.
	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

    go
    // @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
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:

    console
    swag init -g http/api.go -td "[[,]]"

    The new delimiter is a string with the format "<left delimiter>,<right delimiter>".

    Parse Internal and Dependency Packages

    If the struct is defined in a dependency package, use --parseDependency.

    If the struct is defined in your main project, use --parseInternal.

    if you want to include both internal and from dependencies use both flags

    text
    swag init --parseDependency --parseInternal

    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].

    Backers

    Thank you to all our backers! 🙏 [Become a backer]

    Sponsors

    Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]










    License

    File: example/celler/README.md

    Celler example

    Gen doc

    console
    $ go get -u github.com/swaggo/swag/cmd/swag
$ swag init

    Run app

    console
    $ go run main.go

    open swagger

    File: README_pt.md

    swag

    🌍 English ∙ 简体中文 ∙ Português








    Swag converte anotações Go para Documentação Swagger 2.0. Criámos uma variedade de plugins para populares Go web frameworks. Isto permite uma integração rápida com um projecto Go existente (utilizando a Swagger UI).

    Conteúdo

    Começando

    1. Adicione comentários ao código-fonte da API, consulte Formato dos comentários declarativos.

    2. Descarregue o swag utilizando:

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

    Para construir a partir da fonte é necessário Go (1.19 ou mais recente).

    Ou descarregar um binário pré-compilado a partir da página de lançamento.

    1. Executar swag init na pasta raiz do projecto que contém o ficheiro main.go. Isto irá analisar os seus comentários e gerar os ficheiros necessários (pasta docs e docs/docs.go).
    sh
    swag init

    Certifique-se de importar os docs/docs.go gerados para que a sua configuração específica fique "init" ed. Se as suas anotações API gerais não viverem em main.go, pode avisar a swag com a bandeira -g.

    sh
    swag init -g http/api.go
    1. (opcional) Utilizar o formato swag fmt no comentário SWAG. (Por favor, actualizar para a versão mais recente)
    sh
    swag fmt

    swag cli

    sh
    swag init -h
NOME:
   swag init - Criar docs.go

UTILIZAÇÃO:
   swag init [opções de comando] [argumentos...]

OPÇÕES:
   --quiet, -q Fazer o logger ficar quiet (por padrão: falso)
   --generalInfo valor, -g valor Go caminho do ficheiro em que 'swagger general API Info' está escrito (por padrão: "main.go")
   --dir valor, -d valor Os directórios que deseja analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
   --exclude valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
   -propertyStrategy da estratégia, -p valor da propriedadeEstratégia de nomeação de propriedades como snakecase,camelcase,pascalcase (por padrão: "camelcase")
   --output de saída, -o valor directório de saída para todos os ficheiros gerados(swagger.json, swagger.yaml e docs.go) (por padrão: "./docs")
   --outputTypes valor de saídaTypes, -- valor de saída Tipos de ficheiros gerados (docs.go, swagger.json, swagger.yaml) como go,json,yaml (por padrão: "go,json,yaml")
   --parseVendor ParseVendor Parse go files na pasta 'vendor', desactivado por padrão (padrão: falso)
   --parseInternal Parse go ficheiros em pacotes internos, desactivados por padrão (padrão: falso)
   --generatedTime Gerar timestamp no topo dos docs.go, desactivado por padrão (padrão: falso)
   --parteDepth value Dependência profundidade parse (por padrão: 100)
   --templateDelims value, --td value fornecem delimitadores personalizados para a geração de modelos Go. O formato é leftDelim,rightDelim. Por exemplo: "[[,]]"
   ...

   --help, -h mostrar ajuda (por padrão: falso)
    bash
    swag fmt -h
NOME:
   swag fmt - formato swag comentários

UTILIZAÇÃO:
   swag fmt [opções de comando] [argumentos...]

OPÇÕES:
   --dir valor, -d valor Os directórios que pretende analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
   --excluir valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
   --generalInfo value, -g value Go file path in which 'swagger general API Info' is written (por padrão: "main.go")
   --ajuda, -h mostrar ajuda (por padrão: falso)

    Estruturas Web Suportadas

    Como utilizá-lo com Gin

    Encontrar o código fonte de exemplo aqui.

    1. Depois de utilizar swag init para gerar os documentos Swagger 2.0, importar os seguintes pacotes:
    go
    import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
    1. Adicionar Informações Gerais API anotações em código main.go:
    go
    // @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
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")
}
//...

    Além disso, algumas informações API gerais podem ser definidas de forma dinâmica. O pacote de código gerado docs exporta a variável SwaggerInfo que podemos utilizar para definir programticamente o título, descrição, versão, hospedeiro e caminho base. Exemplo utilizando Gin:

    go
    package main

import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	"github.com/swaggo/gin-swagger"

	"./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

	// programmatically set swagger info
	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()

	// use ginSwagger middleware to serve the API docs
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	r.Run()
}
    1. Adicionar Operação API anotações em código controller
    go
    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"
)

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
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)
}

// ListAccounts godoc
// @Summary      List accounts
// @Description  get accounts
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        q    query     string  false  "name search by q"  Format(email)
// @Success      200  {array}   model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts [get]
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)
}
//...
    console
    swag init
    1. Execute a sua aplicação, e navegue para http://localhost:8080/swagger/index.html. Verá os documentos Swagger 2.0 Api, como mostrado abaixo:

    O formatador de swag

    Os Swag Comments podem ser formatados automaticamente, assim como 'go fmt'.
    Encontre o resultado da formatação aqui.

    Usage:

    shell
    swag fmt

    Exclude folder：

    shell
    swag fmt -d ./ --exclude ./internal

    Ao utilizar swag fmt, é necessário assegurar-se de que tem um comentário doc para a função a fim de assegurar uma formatação correcta.
    Isto deve-se ao swag fmt que traça comentários swag com separadores, o que só é permitido após um comentário doc padrão.

    Por exemplo, utilizar

    go
    // ListAccounts lists all existing accounts
//
//  @Summary      List accounts
//  @Description  get accounts
//  @Tags         accounts
//  @Accept       json
//  @Produce      json
//  @Param        q    query     string  false  "name search by q"  Format(email)
//  @Success      200  {array}   model.Account
//  @Failure      400  {object}  httputil.HTTPError
//  @Failure      404  {object}  httputil.HTTPError
//  @Failure      500  {object}  httputil.HTTPError
//  @Router       /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {

    Estado de Implementação

    Documento Swagger 2.0

    • Estrutura básica
    • Hospedeiro API e Caminho Base
    • Caminhos e operações
    • Descrição dos parâmetros
    • Descrever o corpo do pedido
    • Descrição das respostas
    • Tipos MIME
    • Autenticação
      • Autenticação básica
      • Chaves API
    • Acrescentar exemplos
    • Carregamento de ficheiros
    • Enums
    • Operações de Agrupamento com Etiquetas
    • Extensões Swagger

    Formato dos comentários declarativos

    Informações Gerais API

    Exemplo
    celler/main.go

    anotação descrição exemplo
    title Obrigatório. O título da aplicação. // @title Swagger Example API
    version Obrigatório. Fornece a versão da aplicação API. // @version 1.0
    description Uma breve descrição da candidatura. // @descrição Este é um servidor servidor de celas de amostra.
    tag.name Nome de uma tag. // @tag.name Este é o nome da tag
    tag.description Descrição da tag // @tag.description Cool Description
    tag.docs.url Url da Documentação externa da tag // @tag.docs.url https://example.com
    tag.docs.description Descrição da documentação externa da tag // @tag.docs.description Melhor exemplo de documentação
    TermsOfService Os Termos de Serviço para o API. // @termsOfService http://swagger.io/terms/
    contact.name A informação de contacto para a API exposta. // @contacto.name Suporte API
    contact.url O URL que aponta para as informações de contacto. DEVE estar no formato de um URL. // @contact.url http://www.swagger.io/support
    contact.email O endereço de email da pessoa/organização de contacto. DEVE estar no formato de um endereço de correio electrónico. // @contact.email [email protected]
    license.name Obrigatório. O nome da licença utilizada para a API. // @licença.name Apache 2.0
    license.url Um URL para a licença utilizada para a API. DEVE estar no formato de um URL. // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
    host O anfitrião (nome ou ip) que serve o API. // @host localhost:8080
    BasePath O caminho de base sobre o qual o API é servido. // @BasePath /api/v1
    accept Uma lista de tipos de MIME que os APIs podem consumir. Note que accept só afecta operações com um organismo de pedido, tais como POST, PUT e PATCH. O valor DEVE ser o descrito em Tipos de Mime. // @accept json
    produce Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em Tipos de Mime. // @produce json
    query.collection.format O formato padrão de param de colecção(array) em query,enums:csv,multi,pipes,tsv,ssv. Se não definido, csv é o padrão. // @query.collection.format multi
    schemes O protocolo de transferência para a operação que separou por espaços. // @schemes http https
    externalDocs.description Descrição do documento externo. // @externalDocs.description OpenAPI
    externalDocs.url URL do documento externo. // @externalDocs.url https://swagger.io/resources/open-api/
    x-name A chave de extensão, deve ser iniciada por x- e tomar apenas o valor json // @x-example-key {"chave": "valor"}

    Usando descrições de remarcação para baixo

    Quando uma pequena sequência na sua documentação é insuficiente, ou precisa de imagens, exemplos de códigos e coisas do género, pode querer usar descrições de marcação. Para utilizar as descrições markdown, utilize as seguintes anotações.

    anotação descrição exemplo
    title Obrigatório. O título da aplicação. // @title Swagger Example API
    version Obrigatório. Fornece a versão da aplicação API. // @versão 1.0
    description.markdown Uma breve descrição da candidatura. Parsed a partir do ficheiro api.md. Esta é uma alternativa a @description // @description.markdown Sem valor necessário, isto analisa a descrição do ficheiro api.md
    tag.name Nome de uma tag. // @tag.name Este é o nome da tag
    tag.description.markdown Descrição da tag esta é uma alternativa à tag.description. A descrição será lida a partir de um ficheiro nomeado como tagname.md // @tag.description.markdown

    Operação API

    Exemplo
    celler/controller

    anotação descrição
    descrição Uma explicação verbosa do comportamento da operação.
    description.markdown Uma breve descrição da candidatura. A descrição será lida a partir de um ficheiro. Por exemplo, @description.markdown details irá carregar details.md
    id Um fio único utilizado para identificar a operação. Deve ser única entre todas as operações API.
    tags Uma lista de tags para cada operação API que separou por vírgulas.
    summary Um breve resumo do que a operação faz.
    accept Uma lista de tipos de MIME que os APIs podem consumir. Note que accept só afecta operações com um organismo de pedido, tais como POST, PUT e PATCH. O valor DEVE ser o descrito em Tipos de Mime.
    produce Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em Tipos de Mime.
    param Parâmetros que se separaram por espaços. param name,param type,data type,is mandatory?,comment attribute(optional)
    security Segurança para cada operação API.
    success resposta de sucesso que separou por espaços. return code or default,{param type},data type,comment
    failure Resposta de falha que separou por espaços. return code or default,{param type},data type,comment
    response Igual ao sucesso e falha
    header Cabeçalho em resposta que separou por espaços. código de retorno,{tipo de parâmetro},tipo de dados,comentário
    router Definição do caminho que separou por espaços. caminho",path,[httpMethod]
    x-name A chave de extensão, deve ser iniciada por x- e tomar apenas o valor json.
    x-codeSample Optional Markdown use. tomar file como parâmetro. Isto irá então procurar um ficheiro nomeado como o resumo na pasta dada.
    deprecated Marcar o ponto final como depreciado.

    Mime Types

    swag aceita todos os tipos MIME que estão no formato correcto, ou seja, correspondem */*.
    Além disso, swag também aceita pseudónimos para alguns tipos de MIME, como se segue:

    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
    event-stream text/event-stream

    Tipo de parâmetro

    • query
    • path
    • header
    • body
    • formData

    Tipo de dados

    • string (string)
    • integer (int, uint, uint32, uint64)
    • number (float32)
    • boolean (bool)
    • file (param data type when uploading)
    • user defined struct

    Segurança

    anotação descrição parâmetros exemplo
    securitydefinitions.basic Basic auth. // @securityDefinitions.basicAuth
    securitydefinitions.apikey chave API auth. in, name, description // @securityDefinitions.apikey ApiKeyAuth
    securitydefinitions.oauth2.application Aplicação OAuth2 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 código de acesso OAuth2 auth. tokenUrl, authorizationUrl, scope, description // @securitydefinitions.oauth2.accessCode OAuth2AccessCode
    anotação de parâmetros exemplo
    in // @in header
    name // @name Authorization
    tokenUrl // @tokenUrl https://example.com/oauth/token
    authorizationurl // @authorizationurl https://example.com/oauth/authorize
    scope.hoge // @scope.write Grants write access
    description // @descrição OAuth protege os pontos finais da nossa entidade

    Atributo

    go
    // @Param   enumstring  query     string     false  "string enums"       Enums(A, B, C)
// @Param   enumint     query     int        false  "int enums"          Enums(1, 2, 3)
// @Param   enumnumber  query     number     false  "int enums"          Enums(1.1, 1.2, 1.3)
// @Param   string      query     string     false  "string valid"       minlength(5)  maxlength(10)
// @Param   int         query     int        false  "int valid"          minimum(1)    maximum(10)
// @Param   default     query     string     false  "string default"     default(A)
// @Param   example     query     string     false  "string example"     example(string)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

    It also works for the struct fields:

    go
    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"`
}

    Disponível

    Nome do campo Tipo Descrição
    validate string Determina a validação para o parâmetro. Os valores possíveis são: required,optional.
    default * Declara o valor do parâmetro que o servidor utilizará se nenhum for fornecido, por exemplo, uma "contagem" para controlar o número de resultados por página poderá ser por defeito de 100 se não for fornecido pelo cliente no pedido. (Nota: "por defeito" não tem significado para os parâmetros requeridos).
    See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Ao contrário do esquema JSON, este valor DEVE estar em conformidade com o definido type para este parâmetro.
    maximum number Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
    minimum number Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
    multipleOf number Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
    maxLength integer Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
    minLength integer Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
    enums [*] Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
    format string O formato de extensão para o anteriormente mencionado type. Ver Data Type Formats para mais detalhes.
    collectionFormat string Determina o formato da matriz se for utilizada uma matriz de tipos. Os valores possíveis são:
  • csv - valores separados por vírgulas foo,bar.
  • ssv - valores separados por espaço foo bar.
  • tsv - valores separados por tabulação foo\tbar.
  • pipes - valores separados por tubo foo&#124;bar.
  • multi - corresponde a múltiplas instâncias de parâmetros em vez de múltiplos valores para uma única instância foo=bar&foo=baz. This is valid only for parameters in "query" or "formData". Default value is csv.
    		•
    example * Declara o exemplo para o valor do parâmetro
    extensions string Acrescentar extensão aos parâmetros.

    Futuro

    Nome do campo Tipo Description
    pattern string See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
    maxItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
    minItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
    uniqueItems boolean See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.

    Exemplos

    Descrições em múltiplas linhas

    É possível acrescentar descrições que abranjam várias linhas tanto na descrição geral da api como em definições de rotas como esta:

    go
    // @description This is the first line
// @description This is the second line
// @description And so forth.

    Estrutura definida pelo utilizador com um tipo de matriz

    go
    // @Success 200 {array} model.Account <-- This is a user defined struct.
    go
    package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

    Declaração de estruturação de funções

    Pode declarar as estruturas de resposta do seu pedido dentro de um corpo funcional.
    Deve ter de seguir a convenção de nomeação
    .<function-name>.<struct-name> .

    go
    package main

// @Param request body main.MyHandler.request true "query params"
// @Success 200 {object} main.MyHandler.response
// @Router /test [post]
func MyHandler() {
	type request struct {
		RequestField string
	}

	type response struct {
		ResponseField string
	}
}

    Composição do modelo em resposta

    go
    // JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
    go
    type JSONResult struct {
    Code    int          `json:"code" `
    Message string       `json:"message"`
    Data    interface{}  `json:"data"`
}

type Order struct { //in `proto` package
    Id  uint            `json:"id"`
    Data  interface{}   `json:"data"`
}
    • também suportam uma variedade de objectos e tipos primitivos como resposta aninhada
    go
    @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"
    • campos múltiplos que se sobrepõem. campo será adicionado se não existir
    go
    @success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"
    • overriding deep-level fields
    go
    type DeepObject struct { //in `proto` package
	...
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"

    Adicionar um cabeçalho em resposta

    go
    // @Success      200              {string}  string    "ok"
// @failure      400              {string}  string    "error"
// @response     default          {string}  string    "other error"
// @Header       200              {string}  Location  "/entity/1"
// @Header       200,400,default  {string}  Token     "token"
// @Header       all              {string}  Token2    "token2"

    Utilizar parâmetros de caminhos múltiplos

    go
    /// ...
// @Param group_id   path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

    Adicionar múltiplos caminhos

    go
    /// ...
// @Param group_id path int true "Group ID"
// @Param user_id  path int true "User ID"
// ...
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
// @Router /examples/user/{user_id}/address [put]

    Exemplo de valor de estrutura

    go
    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"`
}

    Schema Exemplo do corpo

    go
    // @Param email body string true "message/rfc822" SchemaExample(Subject: Testmail\r\n\r\nBody Message\r\n)

    Descrição da estrutura

    go
    // Account model info
// @Description User account information
// @Description with user id and username
type Account struct {
	// ID this is userid
	ID   int    `json:"id"`
	Name string `json:"name"` // This is Name
}

    #708 O analisador trata apenas de comentários estruturais a partir de @Description attribute.

    Assim, gerou o doc. de swagger como se segue:

    json
    "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"
    }
  }
}

    Usar etiqueta do tipo swaggertype para suportar o tipo personalizado

    #201

    go
    type TimestampTime struct {
    time.Time
}

///implement encoding.JSON.Marshaler interface
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 {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

    // Array types can be overridden using "array," format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

    #379

    go
    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:

    go
    "api.MyBinding": {
  "type":"object",
  "properties":{
    "crt":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    },
    "key":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    }
  }
}

    Utilizar anulações globais para suportar um tipo personalizado

    Se estiver a utilizar ficheiros gerados, as etiquetas swaggertype ou swaggerignore podem não ser possíveis.

    Ao passar um mapeamento para swag com --overridesFile pode dizer swag para utilizar um tipo no lugar de outro onde quer que apareça. Por defeito, se um ficheiro .swaggo estiver presente no directório actual, será utilizado.

    Go code:

    go
    type MyStruct struct {
  ID     sql.NullInt64 `json:"id"`
  Name   sql.NullString `json:"name"`
}

    .swaggo:

    text
    // Substituir todos os NullInt64 por int
replace database/sql.NullInt64 int

// Não inclua quaisquer campos do tipo base de database/sql.
NullString no swagger docs
skip    database/sql.NullString

    As directivas possíveis são comentários (começando por //), replace path/to/a.type path/to/b.type, e skip path/to/a.type.

    (Note que os caminhos completos para qualquer tipo nomeado devem ser fornecidos para evitar problemas quando vários pacotes definem um tipo com o mesmo nome)

    Entregue em:

    go
    "types.MyStruct": {
  "id": "integer"
}

### Use swaggerignore tag para excluir um campo

```go
type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}

    Adicionar informações de extensão ao campo de estruturação

    go
    type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}

    gerar doc. de swagger como se segue:

    go
    "Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def",
            "x-omitempty": false
        }
    }
}

    Renomear modelo a expor

    golang
    type Resp struct {
	Code int
}//@name Response

    Como utilizar as anotações de segurança

    Informações API gerais.

    go
    // @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

    Cada operação API.

    go
    // @Security ApiKeyAuth

    Faça-o OR condicione-o

    go
    // @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

    Faça-o AND condição

    go
    // @Security ApiKeyAuth && firebase
// @Security OAuth2Application[write, admin] && APIKeyAuth

    Adicionar uma descrição para enumerar artigos

    go
    type Example struct {
	// Sort order:
	// * asc - Ascending, from A to Z.
	// * desc - Descending, from Z to A.
	Order string `enums:"asc,desc"`
}

    Gerar apenas tipos de ficheiros de documentos específicos

    Por defeito, o comando swag gera especificação Swagger em três tipos diferentes de ficheiros/arquivos:

    • docs.go
    • swagger.json
    • swagger.yaml

    Se desejar limitar um conjunto de tipos de ficheiros que devem ser gerados pode utilizar a bandeira --outputTypes (short -ot). O valor por defeito é go,json,yaml - tipos de saída separados por vírgula. Para limitar a saída apenas a ficheiros go e yaml, escrever-se-ia go,yaml'. Com comando completo que seria swag init --outputTypes go,yaml`.

    Como usar tipos genéricos

    go
    // @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
func GetPosts(w http.ResponseWriter, r *http.Request) {
	_ = web.GenericNestedResponse[types.Post]{}
}

    Para mais detalhes e outros exemplos, veja esse arquivo

    Alterar os delimitadores de acção padrão Go Template

    #980
    #1177

    Se as suas anotações ou campos estruturantes contêm "{{" or "}}", a geração de modelos irá muito provavelmente falhar, uma vez que estes são os delimitadores por defeito para go templates.

    Para que a geração funcione correctamente, pode alterar os delimitadores por defeito com `-td'. Por exemplo:
    ``console
    swag init -g http/api.go -td "[[,]"

    text
    O novo delimitador é um fio com o formato "`<left delimiter>`,`<right delimiter>`".

## Sobre o projecto
Este projecto foi inspirado por [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) mas simplificámos a utilização e acrescentámos apoio a uma variedade de [frameworks web](#estruturas-web-suportadas). A fonte de imagem Gopher é [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). Tem licenças [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en).

## Contribuidores

Este projecto existe graças a todas as pessoas que contribuem. [[Contribute](CONTRIBUTING.md)].
[](https://github.com/swaggo/swag/graphs/contributors)


## Apoios

Obrigado a todos os nossos apoiantes! 🙏 [[Become a backer](https://opencollective.com/swag#backer)]

[](https://opencollective.com/swag#backers)


## Patrocinadores

Apoiar este projecto tornando-se um patrocinador. O seu logótipo aparecerá aqui com um link para o seu website. [[Become a sponsor](https://opencollective.com/swag#sponsor)]


[](https://opencollective.com/swag/sponsor/0/website)
[](https://opencollective.com/swag/sponsor/1/website)
[](https://opencollective.com/swag/sponsor/2/website)
[](https://opencollective.com/swag/sponsor/3/website)
[](https://opencollective.com/swag/sponsor/4/website)
[](https://opencollective.com/swag/sponsor/5/website)
[](https://opencollective.com/swag/sponsor/6/website)
[](https://opencollective.com/swag/sponsor/7/website)
[](https://opencollective.com/swag/sponsor/8/website)
[](https://opencollective.com/swag/sponsor/9/website)


## Licença
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)

---

## File: README_zh-CN.md

# swag

🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md)*



[](https://travis-ci.org/swaggo/swag)
[](https://codecov.io/gh/swaggo/swag)
[](https://goreportcard.com/report/github.com/swaggo/swag)
[](https://codebeat.co/projects/github-com-swaggo-swag-master)
[](https://godoc.org/github.com/swaggo/swag)
[](#backers)
[](#sponsors) [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)
[](https://github.com/swaggo/swag/releases)

Swag将Go的注释转换为Swagger2.0文档。我们为流行的 [Go Web Framework](#支持的Web框架) 创建了各种插件，这样可以与现有Go项目快速集成（使用Swagger UI）。

## 目录

- [快速开始](#快速开始)
- [支持的Web框架](#支持的web框架)
- [如何与Gin集成](#如何与gin集成)
- [格式化说明](#格式化说明)
- [开发现状](#开发现状)
- [声明式注释格式](#声明式注释格式)
    - [通用API信息](#通用api信息)
    - [API操作](#api操作)
    - [安全性](#安全性)
- [样例](#样例)
    - [多行的描述](#多行的描述)
    - [用户自定义的具有数组类型的结构](#用户自定义的具有数组类型的结构)
    - [响应对象中的模型组合](#响应对象中的模型组合)
    - [在响应中增加头字段](#在响应中增加头字段)
    - [使用多路径参数](#使用多路径参数)
    - [结构体的示例值](#结构体的示例值)
    - [结构体描述](#结构体描述)
    - [使用`swaggertype`标签更改字段类型](#使用`swaggertype`标签更改字段类型)
    - [使用`swaggerignore`标签排除字段](#使用swaggerignore标签排除字段)
    - [将扩展信息添加到结构字段](#将扩展信息添加到结构字段)
    - [对展示的模型重命名](#对展示的模型重命名)
    - [如何使用安全性注释](#如何使用安全性注释)
- [项目相关](#项目相关)

## 快速开始

1. 将注释添加到API源代码中，请参阅声明性注释格式。
2. 使用如下命令下载swag：

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

    从源码开始构建的话，需要有Go环境（1.19及以上版本）。

    或者从github的release页面下载预编译好的二进制文件。

    1. 在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）。
    bash
    swag init

    确保导入了生成的docs/docs.go文件，这样特定的配置文件才会被初始化。如果通用API注释没有写在main.go中，可以使用-g标识符来告知swag。

    bash
    swag init -g http/api.go
    1. (可选) 使用fmt格式化 SWAG 注释。(请先升级到最新版本)
    bash
    swag fmt

    swag cli

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

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

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --parseDependencyLevel, --pdl          对'--parseDependency'参数进行增强, 是否解析依赖目录中的go源文件, 0 不解析, 1 只解析对象模型, 2 只解析API, 3 对象模型和API都解析 (default: 0)
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")
    bash
    swag fmt -h
NAME:
   swag fmt - format swag comments

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

OPTIONS:
   --dir value, -d value          API解析目录 (默认: "./")
   --exclude value                解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --generalInfo value, -g value  API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --help, -h                     show help (default: false)

    支持的Web框架

    如何与Gin集成

    点击此处查看示例源代码。

    1. 使用swag init生成Swagger2.0文档后，导入如下代码包：
    go
    import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
    1. 在main.go源代码中添加通用的API注释：
    go
    // @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
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")
}
//...

    此外，可以动态设置一些通用的API信息。生成的代码包docs导出SwaggerInfo变量，使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例：

    go
    package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"

    "./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

    // programatically set swagger info
    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()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}
    1. 在controller代码中添加API操作注释：
    go
    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"
)

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
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)
}

// ListAccounts godoc
// @Summary      List accounts
// @Description  get accounts
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        q    query     string  false  "name search by q"  Format(email)
// @Success      200  {array}   model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts [get]
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)
}
//...
    bash
    swag init
    1. 运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档，如下所示：

    格式化说明

    可以针对Swag的注释自动格式化，就像go fmt。
    此处查看格式化结果 here.

    示例：

    shell
    swag fmt

    排除目录（不扫描）示例：

    shell
    swag fmt -d ./ --exclude ./internal

    开发现状

    Swagger 2.0 文档

    • Basic Structure
    • API Host and Base Path
    • Paths and Operations
    • Describing Parameters
    • Describing Request Body
    • Describing Responses
    • MIME Types
    • Authentication
      • Basic Authentication
      • API Keys
    • Adding Examples
    • File Upload
    • Enums
    • Grouping Operations With Tags
    • Swagger Extensions

    声明式注释格式

    通用API信息

    示例 celler/main.go

    注释 说明 示例
    title 必填 应用程序的名称。 // @title Swagger Example API
    version 必填 提供应用程序API的版本。 // @version 1.0
    description 应用程序的简短描述。 // @description This is a sample server celler server.
    tag.name 标签的名称。 // @tag.name This is the name of the tag
    tag.description 标签的描述。 // @tag.description Cool Description
    tag.docs.url 标签的外部文档的URL。 // @tag.docs.url https://example.com
    tag.docs.description 标签的外部文档说明。 // @tag.docs.description Best example documentation
    termsOfService API的服务条款。 // @termsOfService http://swagger.io/terms/
    contact.name 公开的API的联系信息。 // @contact.name API Support
    contact.url 联系信息的URL。 必须采用网址格式。 // @contact.url http://www.swagger.io/support
    contact.email 联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。 // @contact.email [email protected]
    license.name 必填 用于API的许可证名称。 // @license.name Apache 2.0
    license.url 用于API的许可证的URL。 必须采用网址格式。 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
    host 运行API的主机（主机名或IP地址）。 // @host localhost:8080
    BasePath 运行API的基本路径。 // @BasePath /api/v1
    accept API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。 // @accept json
    produce API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。 // @produce json
    query.collection.format 请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。 // @query.collection.format multi
    schemes 用空格分隔的请求的传输协议。 // @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 扩展的键必须以x-开头，并且只能使用json值 // @x-example-key {"key": "value"}

    使用Markdown描述

    如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。

    注释 说明 示例
    title 必填 应用程序的名称。 // @title Swagger Example API
    version 必填 提供应用程序API的版本。 // @version 1.0
    description.markdown 应用程序的简短描述。 从api.md文件中解析。 这是@description的替代用法。 // @description.markdown No value needed, this parses the description from api.md
    tag.name 标签的名称。 // @tag.name This is the name of the tag
    tag.description.markdown 标签说明，这是tag.description的替代用法。 该描述将从名为tagname.md的文件中读取。 // @tag.description.markdown

    API操作

    Example celler/controller

    注释 描述
    description 操作行为的详细说明。
    description.markdown 应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。
    id 用于标识操作的唯一字符串。在所有API操作中必须唯一。
    tags 每个API操作的标签列表，以逗号分隔。
    summary 该操作的简短摘要。
    accept API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
    produce API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
    param 用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
    security 每个API操作的安全性。
    success 以空格分隔的成功响应。return code,{param type},data type,comment
    failure 以空格分隔的故障响应。return code,{param type},data type,comment
    response 与success、failure作用相同
    header 以空格分隔的头字段。 return code,{param type},data type,comment
    router 以空格分隔的路径定义。 path,[httpMethod]
    deprecatedrouter 与router相同，但是是deprecated的。
    x-name 扩展字段必须以x-开头，并且只能使用json值。
    deprecated 将当前API操作的所有路径设置为deprecated

    Mime类型

    swag 接受所有格式正确的MIME类型, 即使匹配 */*。除此之外，swag还接受某些MIME类型的别名，如下所示：

    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
    event-stream text/event-stream

    参数类型

    • query
    • path
    • header
    • body
    • formData

    数据类型

    • string (string)
    • integer (int, uint, uint32, uint64)
    • number (float32)
    • boolean (bool)
    • user defined struct

    安全性

    注释 描述 参数 示例
    securitydefinitions.basic Basic auth. // @securityDefinitions.basic BasicAuth
    securitydefinitions.apikey API key auth. in, name // @securityDefinitions.apikey ApiKeyAuth
    securitydefinitions.oauth2.application OAuth2 application auth. tokenUrl, scope // @securitydefinitions.oauth2.application OAuth2Application
    securitydefinitions.oauth2.implicit OAuth2 implicit auth. authorizationUrl, scope // @securitydefinitions.oauth2.implicit OAuth2Implicit
    securitydefinitions.oauth2.password OAuth2 password auth. tokenUrl, scope // @securitydefinitions.oauth2.password OAuth2Password
    securitydefinitions.oauth2.accessCode OAuth2 access code auth. tokenUrl, authorizationUrl, scope // @securitydefinitions.oauth2.accessCode OAuth2AccessCode
    参数注释 示例
    in // @in header
    name // @name Authorization
    tokenUrl // @tokenUrl https://example.com/oauth/token
    authorizationurl // @authorizationurl https://example.com/oauth/authorize
    scope.hoge // @scope.write Grants write access

    属性

    go
    // @Param   enumstring  query     string     false  "string enums"       Enums(A, B, C)
// @Param   enumint     query     int        false  "int enums"          Enums(1, 2, 3)
// @Param   enumnumber  query     number     false  "int enums"          Enums(1.1, 1.2, 1.3)
// @Param   string      query     string     false  "string valid"       minlength(5)  maxlength(10)
// @Param   int         query     int        false  "int valid"          minimum(1)    maximum(10)
// @Param   default     query     string     false  "string default"     default(A)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

    也适用于结构体字段：

    go
    type Foo struct {
    Bar string `minLength:"4" maxLength:"16"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux []string `enums:"foo,bar,baz"`
}

    当前可用的

    字段名 类型 描述
    default * 声明如果未提供任何参数，则服务器将使用的默认参数值，例如，如果请求中的客户端未提供该参数，则用于控制每页结果数的“计数”可能默认为100。 （注意：“default”对于必需的参数没有意义）。参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。 与JSON模式不同，此值务必符合此参数的定义类型。
    maximum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
    minimum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
    maxLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
    minLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
    enums [*] 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
    format string 上面提到的类型的扩展格式。有关更多详细信息，请参见数据类型格式。
    collectionFormat string 指定query数组参数的格式。 可能的值为：
  • csv - 逗号分隔值 foo,bar.
  • ssv - 空格分隔值 foo bar.
  • tsv - 制表符分隔值 foo\tbar.
  • pipes - 管道符分隔值 foo&#124;bar.
  • multi - 对应于多个参数实例，而不是单个实例 foo=bar＆foo=baz 的多个值。这仅对“query”或“formData”中的参数有效。 默认值是 csv。
    		•

    进一步的

    字段名 类型 描述
    multipleOf number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
    pattern string See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
    maxItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
    minItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
    uniqueItems boolean See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.

    样例

    多行的描述

    可以在常规api描述或路由定义中添加跨越多行的描述，如下所示：

    go
    // @description This is the first line
// @description This is the second line
// @description And so forth.

    用户自定义的具有数组类型的结构

    go
    // @Success 200 {array} model.Account <-- This is a user defined struct.
    go
    package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

    响应对象中的模型组合

    go
    // JSONResult的data字段类型将被proto.Order类型替换
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"
    go
    type JSONResult struct {
    Code    int          `json:"code" `
    Message string       `json:"message"`
    Data    interface{}  `json:"data"`
}

type Order struct { //in `proto` package
    ...
}
    • 还支持对象数组和原始类型作为嵌套响应
    go
    @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"
    • 替换多个字段的类型。如果某字段不存在，将添加该字段。
    go
    @success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"

    在响应中增加头字段

    go
    // @Success      200              {string}  string    "ok"
// @failure      400              {string}  string    "error"
// @response     default          {string}  string    "other error"
// @Header       200              {string}  Location  "/entity/1"
// @Header       200,400,default  {string}  Token     "token"
// @Header       all              {string}  Token2    "token2"

    使用多路径参数

    go
    /// ...
// @Param  group_id    path  int  true  "Group ID"
// @Param  account_id  path  int  true  "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

    结构体的示例值

    go
    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"`
}

    结构体描述

    go
    type Account struct {
    // ID this is userid
    ID   int    `json:"id"`
    Name string `json:"name"` // This is Name
}

    使用`swaggertype`标签更改字段类型

    #201

    go
    type TimestampTime struct {
    time.Time
}

///实现encoding.JSON.Marshaler接口
func (t *TimestampTime) MarshalJSON() ([]byte, error) {
    bin := make([]byte, 16)
    bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
    return bin, nil
}

///实现encoding.JSON.Unmarshaler接口
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 {
    // 使用`swaggertype`标签将别名类型更改为内置类型integer
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`

    // 使用`swaggertype`标签更改struct类型为内置类型integer
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`

    // Array types can be overridden using "array," format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

    #379

    go
    type CerticateKeyPair struct {
    Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
    Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}

    生成的swagger文档如下：

    go
    "api.MyBinding": {
  "type":"object",
  "properties":{
    "crt":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    },
    "key":{
      "type":"string",
      "format":"base64",
      "example":"U3dhZ2dlciByb2Nrcw=="
    }
  }
}

    使用`swaggerignore`标签排除字段

    go
    type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}

    将扩展信息添加到结构字段

    go
    type Account struct {
    ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // 扩展字段必须以"x-"开头
}

    生成swagger文档，如下所示：

    go
    "Account": {
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "x-nullable": true,
            "x-abc": "def",
            "x-omitempty": false
        }
    }
}

    对展示的模型重命名

    go
    type Resp struct {
    Code int
}//@name Response

    如何使用安全性注释

    通用API信息。

    go
    // @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

    每个API操作。

    go
    // @Security ApiKeyAuth

    使用AND条件。

    go
    // @Security ApiKeyAuth && OAuth2Application[write, admin]

    项目相关

    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.

    贡献者

    This project exists thanks to all the people who contribute. [Contribute].

    支持者

    Thank you to all our backers! 🙏 [Become a backer]

    赞助商

    Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]










    License

    Explore Related Technologies & Topics

    View All 9,111+ Repositories →

    Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

    #annotations Browse annotations catalog → #golang Browse golang catalog → #openapi Browse openapi catalog → #swagger Browse swagger catalog → #swagger2 Browse swagger2 catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →