## File: README.md # swag 🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md) ∙ [Português](README_pt.md)* [](https://github.com/features/actions) [](https://codecov.io/gh/swaggo/swag) [](https://goreportcard.com/report/github.com/swaggo/swag) [](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 converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular [Go web frameworks](#supported-web-frameworks). This allows you to quickly integrate with an existing Go project (using Swagger UI). ## Contents - [Getting started](#getting-started) - [Supported Web Frameworks](#supported-web-frameworks) - [How to use it with Gin](#how-to-use-it-with-gin) - [The swag formatter](#the-swag-formatter) - [Implementation Status](#implementation-status) - [Declarative Comments Format](#declarative-comments-format) - [General API Info](#general-api-info) - [API Operation](#api-operation) - [Security](#security) - [Examples](#examples) - [Descriptions over multiple lines](#descriptions-over-multiple-lines) - [User defined structure with an array type](#user-defined-structure-with-an-array-type) - [Function scoped struct declaration](#function-scoped-struct-declaration) - [Model composition in response](#model-composition-in-response) - [Add request headers](#add-request-headers) - [Add response headers](#add-response-headers) - [Use multiple path params](#use-multiple-path-params) - [Example value of struct](#example-value-of-struct) - [SchemaExample of body](#schemaexample-of-body) - [Description of struct](#description-of-struct) - [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type) - [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type) - [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field) - [Add extension info to struct field](#add-extension-info-to-struct-field) - [Rename model to display](#rename-model-to-display) - [How to use security annotations](#how-to-use-security-annotations) - [Add a description for enum items](#add-a-description-for-enum-items) - [Generate only specific docs file types](#generate-only-specific-docs-file-types) - [How to use Go generic types](#how-to-use-generics) - [About the Project](#about-the-project) ## Getting started 1. Add comments to your API source code, See [Declarative Comments Format](#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](https://golang.org/dl/) (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](https://github.com/swaggo/swag/releases). 3. 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 ``` 4. (optional) Use `swag fmt` format the SWAG comment. (Please upgrade to the latest version) ```sh swag fmt ``` ## swag cli ``` /* 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 - [gin](http://github.com/swaggo/gin-swagger) - [echo](http://github.com/swaggo/echo-swagger) - [buffalo](https://github.com/swaggo/buffalo-swagger) - [net/http](https://github.com/swaggo/http-swagger) - [gorilla/mux](https://github.com/swaggo/http-swagger) - [go-chi/chi](https://github.com/swaggo/http-swagger) - [flamingo](https://github.com/i-love-flamingo/swagger) - [fiber](https://github.com/gofiber/swagger) - [atreugo](https://github.com/Nerzal/atreugo-swagger) - [hertz](https://github.com/hertz-contrib/swagger) ## How to use it with Gin Find the example source code [here](https://github.com/swaggo/swag/tree/master/example/celler). Finish the steps in [Getting started](#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 ``` 2. Add [General API](#general-api-info) 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 support@swagger.io // @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 support@swagger.io // @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() } ``` 3. Add [API Operation](#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 ``` 4. 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](https://github.com/swaggo/swag/tree/master/example/celler). 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](https://swagger.io/docs/specification/2-0/basic-structure/) - [x] Basic Structure - [x] API Host and Base Path - [x] Paths and Operations - [x] Describing Parameters - [x] Describing Request Body - [x] Describing Responses - [x] MIME Types - [x] Authentication - [x] Basic Authentication - [x] API Keys - [x] Adding Examples - [x] File Upload - [x] Enums - [x] Grouping Operations With Tags - [ ] Swagger Extensions # Declarative Comments Format ## General API Info **Example** [celler/main.go](https://github.com/swaggo/swag/blob/master/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](#mime-types). | // @accept json | | produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#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](https://github.com/swaggo/swag/tree/master/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` | // @description.file endpoint.description.markdown | | 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](#mime-types). | | produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). | | param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` | | security | [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](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth | | securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth | | securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application | | securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit | | securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password | | securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) 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`](#parameterType) 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`](#parameterType). See [Data Type Formats](https://swagger.io/specification/v2/#dataTypeFormat) 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`](#parameterIn) "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 `.. `. ```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](https://github.com/swaggo/swag/issues/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](https://github.com/swaggo/swag/issues/201#issuecomment-475479409) ```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](https://github.com/swaggo/swag/issues/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`](#use-swaggertype-tag-to-supported-custom-type) 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`: ``` // 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](https://github.com/swaggo/swag/blob/master/testdata/generics_nested/api/api.go) for more details and other examples. ### Change the default Go Template action delimiters [#980](https://github.com/swaggo/swag/issues/980) [#1177](https://github.com/swaggo/swag/issues/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](https://pkg.go.dev/text/template#Template.Delims). 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 "``,``". ### 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 ``` swag init --parseDependency --parseInternal ``` ## About the Project This project was inspired by [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). It has licenses [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en). ## Contributors This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. [](https://github.com/swaggo/swag/graphs/contributors) ## Backers Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)] [](https://opencollective.com/swag#backers) ## Sponsors 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)] [](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) ## License [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large) --- ## 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](http://localhost:8080/swagger/index.html) --- ## File: README_pt.md # swag 🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md) ∙ [Português](README_pt.md)* [](https://github.com/features/actions) [](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 converte anotações Go para Documentação Swagger 2.0. Criámos uma variedade de plugins para populares [Go web frameworks](#supported-web-frameworks). Isto permite uma integração rápida com um projecto Go existente (utilizando a Swagger UI). ## Conteúdo - [Começando](#começando) - [Estruturas Web Suportadas](#estruturas-web-suportadas) - [Como utilizá-lo com Gin](#como-como-ser-como-gin) - [O formatador de swag](#a-formatação-de-swag) - [Estado de Implementação](#implementação-estado) - [Formato dos comentários declarativos](#formato-dos-comentarios-declarativos) - [Informações Gerais API](#informações-gerais-api) - [Operação API](#api-operacao) - [Segurança](#seguranca) - [Exemplos](#exemplos) - [Descrições em múltiplas linhas](#descricoes-sobre-múltiplas-linhas) - [Estrutura definida pelo utilizador com um tipo de matriz](#-estrutura-definida-pelo-utilizador-com-um-um-tipo) - [Declaração de estruturação de funções](#function-scoped-struct-declaration) - [Composição do modelo em resposta](#model-composição-em-resposta) - [Adicionar um cabeçalho em resposta](#add-a-headers-in-response) - [Utilizar parâmetros de caminhos múltiplos](#use-multiple-path-params) - [Exemplo de valor de estrutura](#exemplo-do-valor-de-estrutura) - [Schema Exemplo do corpo](#schemaexample-of-body) - [Descrição da estrutura](#descrição-da-estrutura) - [Usar etiqueta do tipo swaggertype para suportar o tipo personalizado](#use-swaggertype-tag-to-supported-custom-type) - [Utilizar anulações globais para suportar um tipo personalizado](#use-global-overrides-to-support-a-custom-type) - [Use swaggerignore tag para excluir um campo](#use-swaggerignore-tag-to-excluir-um-campo) - [Adicionar informações de extensão ao campo de estruturação](#add-extension-info-to-struct-field) - [Renomear modelo a expor](#renome-modelo-a-exibir) - [Como utilizar as anotações de segurança](#como-utilizar-as-anotações-de-segurança) - [Adicionar uma descrição para enumerar artigos](#add-a-description-for-enum-items) - [Gerar apenas tipos de ficheiros de documentos específicos](#generate-only-specific-docs-file-file-types) - [Como usar tipos genéricos](#como-usar-tipos-genéricos) - [Sobre o projecto](#sobre-o-projecto) ## Começando 1. Adicione comentários ao código-fonte da API, consulte [Formato dos comentários declarativos](#declarative-comments-format). 2. Descarregue o swag utilizando: ```sh go install github.com/swaggo/swag/cmd/swag@latest ``` Para construir a partir da fonte é necessário [Go](https://golang.org/dl/) (1.19 ou mais recente). Ou descarregar um binário pré-compilado a partir da [página de lançamento](https://github.com/swaggo/swag/releases). 3. 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 ``` 4. (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 - [gin](http://github.com/swaggo/gin-swagger) - [echo](http://github.com/swaggo/echo-swagger) - [buffalo](https://github.com/swaggo/buffalo-swagger) - [net/http](https://github.com/swaggo/http-swagger) - [gorilla/mux](https://github.com/swaggo/http-swagger) - [go-chi/chi](https://github.com/swaggo/http-swagger) - [flamingo](https://github.com/i-love-flamingo/swagger) - [fiber](https://github.com/gofiber/swagger) - [atreugo](https://github.com/Nerzal/atreugo-swagger) - [hertz](https://github.com/hertz-contrib/swagger) ## Como utilizá-lo com Gin Encontrar o código fonte de exemplo [aqui](https://github.com/swaggo/swag/tree/master/example/celler). 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 ``` 2. Adicionar [Informações Gerais API](#general-api-info) 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 support@swagger.io // @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 support@swagger.io // @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() } ``` 3. Adicionar [Operação API](#api-operacao) 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 ``` 4. 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](https://github.com/swaggo/swag/tree/master/example/celler). 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](https://swagger.io/docs/specification/2-0/basic-structure/) - [x] Estrutura básica - [x] Hospedeiro API e Caminho Base - [x] Caminhos e operações - [x] Descrição dos parâmetros - [x] Descrever o corpo do pedido - [x] Descrição das respostas - [x] Tipos MIME - [x] Autenticação - [x] Autenticação básica - [x] Chaves API - [x] Acrescentar exemplos - [x] Carregamento de ficheiros - [x] Enums - [x] Operações de Agrupamento com Etiquetas - Extensões Swagger ## Formato dos comentários declarativos ## Informações Gerais API **Exemplo** [celler/main.go](https://github.com/swaggo/swag/blob/master/example/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 support@swagger.io | | 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](#mime-types). | // @accept json | | produce | Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). | // @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](https://github.com/swaggo/swag/tree/master/example/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`| // @description.file endpoint.description.markdown | | 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](#mime-types). | | produce | Uma lista de tipos de MIME que os APIs podem produce. O valor DEVE ser o descrito em [Tipos de Mime](#mime-types). | | param | Parâmetros que se separaram por espaços. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` | | security | [Segurança](#security) 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]` |[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](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basicAuth | [Básico]() | securitydefinitions.apikey | [chave API](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name, description | // @securityDefinitions.apikey ApiKeyAuth | | securitydefinitions.oauth2.application | [Aplicação OAuth2](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.application OAuth2Application | | securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope, description | // @securitydefinitions.oauth2.implicit OAuth2Implicit | [OAuth2Implicit]() | securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope, description | // @securitydefinitions.oauth2.password OAuth2Password | | securitydefinitions.oauth2.accessCode | [código de acesso OAuth2](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, authorizationUrl, scope, description | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode | [código de acesso OAuth2.accessCode]() | 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`](#parameterType) 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`](#parameterType). Ver [Data Type Formats](https://swagger.io/specification/v2/#dataTypeFormat) 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|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`](#parameterIn) "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 `.. `. ```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](https://github.com/swaggo/swag/issues/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](https://github.com/swaggo/swag/issues/201#issuecomment-475479409) ```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](https://github.com/swaggo/swag/issues/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`](#use-swaggertype-tag-to-supported-custom-type) 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`: ``` // 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](https://github.com/swaggo/swag/blob/master/testdata/generics_nested/api/api.go) ### Alterar os delimitadores de acção padrão Go Template [#980](https://github.com/swaggo/swag/issues/980) [#1177](https://github.com/swaggo/swag/issues/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](https://pkg.go.dev/text/template#Template.Delims). 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 "[[,]" ``` O novo delimitador é um fio com o formato "``,``". ## 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页面下载预编译好的二进制文件。 3. 在包含`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 ``` 4. (可选) 使用`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](http://github.com/swaggo/gin-swagger) - [echo](http://github.com/swaggo/echo-swagger) - [buffalo](https://github.com/swaggo/buffalo-swagger) - [net/http](https://github.com/swaggo/http-swagger) - [gorilla/mux](https://github.com/swaggo/http-swagger) - [go-chi/chi](https://github.com/swaggo/http-swagger) - [flamingo](https://github.com/i-love-flamingo/swagger) - [fiber](https://github.com/gofiber/swagger) - [atreugo](https://github.com/Nerzal/atreugo-swagger) - [hertz](https://github.com/hertz-contrib/swagger) ## 如何与Gin集成 [点击此处](https://github.com/swaggo/swag/tree/master/example/celler)查看示例源代码。 1. 使用`swag init`生成Swagger2.0文档后，导入如下代码包： ```go import "github.com/swaggo/gin-swagger" // gin-swagger middleware import "github.com/swaggo/files" // swagger embed files ``` 2. 在`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 support@swagger.io // @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 support@swagger.io // @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() } ``` 3. 在`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 ``` 4. 运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档，如下所示： ## 格式化说明 可以针对Swag的注释自动格式化，就像`go fmt`。 此处查看格式化结果 [here](https://github.com/swaggo/swag/tree/master/example/celler). 示例： ```shell swag fmt ``` 排除目录（不扫描）示例： ```shell swag fmt -d ./ --exclude ./internal ``` ## 开发现状 [Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/) - [x] Basic Structure - [x] API Host and Base Path - [x] Paths and Operations - [x] Describing Parameters - [x] Describing Request Body - [x] Describing Responses - [x] MIME Types - [x] Authentication - [x] Basic Authentication - [x] API Keys - [x] Adding Examples - [x] File Upload - [x] Enums - [x] Grouping Operations With Tags - [ ] Swagger Extensions ## 声明式注释格式 ## 通用API信息 **示例** [`celler/main.go`](https://github.com/swaggo/swag/blob/master/example/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 support@swagger.io | | 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类型](#mime类型)”中所述。 | // @accept json | | produce | API可以生成的MIME类型的列表。值必须如“[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](https://github.com/swaggo/swag/tree/master/example/celler/controller) | 注释 | 描述 | |----------------------|------------------------------------------------------------------------------------------------| | description | 操作行为的详细说明。 | | description.markdown | 应用程序的简短描述。该描述将从名为`endpointname.md`的文件中读取。 | | id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 | | tags | 每个API操作的标签列表，以逗号分隔。 | | summary | 该操作的简短摘要。 | | accept | API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“[Mime类型](#mime类型)”中所述。 | | produce | API可以生成的MIME类型的列表。值必须如“[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](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | | // @securityDefinitions.basic BasicAuth | | securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name | // @securityDefinitions.apikey ApiKeyAuth | | securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope | // @securitydefinitions.oauth2.application OAuth2Application | | securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope | // @securitydefinitions.oauth2.implicit OAuth2Implicit | | securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope | // @securitydefinitions.oauth2.password OAuth2Password | | securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) 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模式不同，此值务必符合此参数的定义[类型](#parameterType)。 | | 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` | 上面提到的[类型](#parameterType)的扩展格式。有关更多详细信息，请参见[数据类型格式](https://swagger.io/specification/v2/#dataTypeFormat)。 | | collectionFormat | `string` | 指定query数组参数的格式。 可能的值为：
  • `csv` - 逗号分隔值 `foo,bar`.
  • `ssv` - 空格分隔值 `foo bar`.
  • `tsv` - 制表符分隔值 `foo\tbar`.
  • `pipes` - 管道符分隔值 `foo|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](https://github.com/swaggo/swag/issues/201#issuecomment-475479409) ```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](https://github.com/swaggo/swag/issues/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](https://github.com/yvasiyarov/swagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). It has licenses [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en). ## 贡献者 This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. [](https://github.com/swaggo/swag/graphs/contributors) ## 支持者 Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/swag#backer)] [](https://opencollective.com/swag#backers) ## 赞助商 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)] [](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) ## License [](https://app.fossa.io/projects/git%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)