[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-4964":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":19,"lastSyncTime":34,"discoverSource":35},4964,"swag","swaggo\u002Fswag","swaggo","Automatically generate RESTful API documentation with Swagger 2.0 for Go.","",null,"Go",12841,1372,88,397,0,10,60,2,44.41,"MIT License",false,"master",true,[26,27,28,29,30],"annotations","golang","openapi","swagger","swagger2","2026-06-12 02:01:06","# swag\n\n🌍 *[English](README.md) ∙ [简体中文](README_zh-CN.md) ∙ [Português](README_pt.md)*\n\n\u003Cimg align=\"right\" width=\"180px\" src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fswaggo\u002Fswag\u002Fmaster\u002Fassets\u002Fswaggo.png\">\n\n[![Build Status](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg?branch=master)](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Factions)\n[![Coverage Status](https:\u002F\u002Fimg.shields.io\u002Fcodecov\u002Fc\u002Fgithub\u002Fswaggo\u002Fswag\u002Fmaster.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fswaggo\u002Fswag)\n[![Go Report Card](https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fswaggo\u002Fswag)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fswaggo\u002Fswag)\n[![Go Doc](https:\u002F\u002Fgodoc.org\u002Fgithub.com\u002Fswaggo\u002Fswagg?status.svg)](https:\u002F\u002Fgodoc.org\u002Fgithub.com\u002Fswaggo\u002Fswag)\n[![Backers on Open Collective](https:\u002F\u002Fopencollective.com\u002Fswag\u002Fbackers\u002Fbadge.svg)](#backers)\n[![Sponsors on Open Collective](https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsors\u002Fbadge.svg)](#sponsors) [![FOSSA Status](https:\u002F\u002Fapp.fossa.io\u002Fapi\u002Fprojects\u002Fgit%2Bgithub.com%2Fswaggo%2Fswag.svg?type=shield)](https:\u002F\u002Fapp.fossa.io\u002Fprojects\u002Fgit%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_shield)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Frelease\u002Fswaggo\u002Fswag.svg?style=flat-square)](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Freleases)\n\n\nSwag 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).\n\n## Contents\n - [Getting started](#getting-started)\n - [Supported Web Frameworks](#supported-web-frameworks)\n - [How to use it with Gin](#how-to-use-it-with-gin)\n - [The swag formatter](#the-swag-formatter)\n - [Implementation Status](#implementation-status)\n - [Declarative Comments Format](#declarative-comments-format)\n\t- [General API Info](#general-api-info)\n\t- [API Operation](#api-operation)\n\t- [Security](#security)\n - [Examples](#examples)\n\t- [Descriptions over multiple lines](#descriptions-over-multiple-lines)\n\t- [User defined structure with an array type](#user-defined-structure-with-an-array-type)\n\t- [Function scoped struct declaration](#function-scoped-struct-declaration)\n\t- [Model composition in response](#model-composition-in-response)\n        - [Add request headers](#add-request-headers)\n\t- [Add response headers](#add-response-headers)\n\t- [Use multiple path params](#use-multiple-path-params)\n\t- [Example value of struct](#example-value-of-struct)\n\t- [SchemaExample of body](#schemaexample-of-body)\n\t- [Description of struct](#description-of-struct)\n\t- [Use swaggertype tag to supported custom type](#use-swaggertype-tag-to-supported-custom-type)\n\t- [Use global overrides to support a custom type](#use-global-overrides-to-support-a-custom-type)\n\t- [Use swaggerignore tag to exclude a field](#use-swaggerignore-tag-to-exclude-a-field)\n\t- [Add extension info to struct field](#add-extension-info-to-struct-field)\n\t- [Rename model to display](#rename-model-to-display)\n\t- [How to use security annotations](#how-to-use-security-annotations)\n\t- [Add a description for enum items](#add-a-description-for-enum-items)\n\t- [Generate only specific docs file types](#generate-only-specific-docs-file-types)\n    - [How to use Go generic types](#how-to-use-generics)\n- [About the Project](#about-the-project)\n\n## Getting started\n\n1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).\n\n2. Install swag by using:\n```sh\ngo install github.com\u002Fswaggo\u002Fswag\u002Fcmd\u002Fswag@latest\n```\nTo build from source you need [Go](https:\u002F\u002Fgolang.org\u002Fdl\u002F) (1.19 or newer).\n\nAlternatively you can run the docker image:\n```sh\ndocker run --rm -v $(pwd):\u002Fcode ghcr.io\u002Fswaggo\u002Fswag:latest\n```\n\nOr download a pre-compiled binary from the [release page](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Freleases).\n\n3. 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\u002Fdocs.go`).\n```sh\nswag init\n```\n\n  Make sure to import the generated `docs\u002Fdocs.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.\n  ```go\n  import _ \"example-module-name\u002Fdocs\"\n  ```\n  ```sh\n  swag init -g http\u002Fapi.go\n  ```\n\n4. (optional) Use `swag fmt` format the SWAG comment. (Please upgrade to the latest version)\n\n  ```sh\n  swag fmt\n  ```\n\n## swag cli\n\n```sh\nswag init -h\nNAME:\n   swag init - Create docs.go\n\nUSAGE:\n   swag init [command options] [arguments...]\n\nOPTIONS:\n   --quiet, -q                            Make the logger quiet. (default: false)\n   --generalInfo value, -g value          Go file path in which 'swagger general API Info' is written (default: \"main.go\")\n   --dir value, -d value                  Directories you want to parse,comma separated and general-info file must be in the first one (default: \".\u002F\")\n   --exclude value                        Exclude directories and files when searching, comma separated\n   --propertyStrategy value, -p value     Property Naming Strategy like snakecase,camelcase,pascalcase (default: \"camelcase\")\n   --output value, -o value               Output directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: \".\u002Fdocs\")\n   --outputTypes value, --ot value        Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: \"go,json,yaml\")\n   --parseVendor                          Parse go files in 'vendor' folder, disabled by default (default: false)\n   --parseDependency, --pd                Parse go files inside dependency folder, disabled by default (default: false)\n   --parseDependencyLevel, --pdl          Enhancement of '--parseDependency', parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)\n   --markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default\n   --codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default\n   --parseInternal                        Parse go files in internal packages, disabled by default (default: false)\n   --generatedTime                        Generate timestamp at the top of docs.go, disabled by default (default: false)\n   --parseDepth value                     Dependency parse depth (default: 100)\n   --requiredByDefault                    Set validation required for all fields by default (default: false)\n   --instanceName value                   This parameter can be used to name different swagger document instances. It is optional.\n   --overridesFile value                  File to read global type overrides from. (default: \".swaggo\")\n   --parseGoList                          Parse dependency via 'go list' (default: true)\n   --tags value, -t value                 A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded\n   --templateDelims value, --td value     Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: \"[[,]]\"\n   --collectionFormat value, --cf value   Set default collection format (default: \"csv\")\n   --state value                          Initial state for the state machine (default: \"\"), @HostState in root file, @State in other files\n   --parseFuncBody                        Parse API info within body of functions in go files, disabled by default (default: false)\n   --help, -h                             show help (default: false)\n```\n\n```bash\nswag fmt -h\nNAME:\n   swag fmt - format swag comments\n\nUSAGE:\n   swag fmt [command options] [arguments...]\n\nOPTIONS:\n   --dir value, -d value          Directories you want to parse,comma separated and general-info file must be in the first one (default: \".\u002F\")\n   --exclude value                Exclude directories and files when searching, comma separated\n   --generalInfo value, -g value  Go file path in which 'swagger general API Info' is written (default: \"main.go\")\n   --help, -h                     show help (default: false)\n\n```\n\n## Supported Web Frameworks\n\n- [gin](http:\u002F\u002Fgithub.com\u002Fswaggo\u002Fgin-swagger)\n- [echo](http:\u002F\u002Fgithub.com\u002Fswaggo\u002Fecho-swagger)\n- [buffalo](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fbuffalo-swagger)\n- [net\u002Fhttp](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fhttp-swagger)\n- [gorilla\u002Fmux](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fhttp-swagger)\n- [go-chi\u002Fchi](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fhttp-swagger)\n- [flamingo](https:\u002F\u002Fgithub.com\u002Fi-love-flamingo\u002Fswagger)\n- [fiber](https:\u002F\u002Fgithub.com\u002Fgofiber\u002Fswagger)\n- [atreugo](https:\u002F\u002Fgithub.com\u002FNerzal\u002Fatreugo-swagger)\n- [hertz](https:\u002F\u002Fgithub.com\u002Fhertz-contrib\u002Fswagger)\n\n## How to use it with Gin\n\nFind the example source code [here](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Ftree\u002Fmaster\u002Fexample\u002Fceller).\n\nFinish the steps in [Getting started](#getting-started)\n1. After using `swag init` to generate Swagger 2.0 docs, import the following packages:\n```go\nimport \"github.com\u002Fswaggo\u002Fgin-swagger\" \u002F\u002F gin-swagger middleware\nimport \"github.com\u002Fswaggo\u002Ffiles\" \u002F\u002F swagger embed files\n```\n\n2. Add [General API](#general-api-info) annotations in `main.go` code:\n\n```go\n\u002F\u002F @title           Swagger Example API\n\u002F\u002F @version         1.0\n\u002F\u002F @description     This is a sample server celler server.\n\u002F\u002F @termsOfService  http:\u002F\u002Fswagger.io\u002Fterms\u002F\n\n\u002F\u002F @contact.name   API Support\n\u002F\u002F @contact.url    http:\u002F\u002Fwww.swagger.io\u002Fsupport\n\u002F\u002F @contact.email  support@swagger.io\n\n\u002F\u002F @license.name  Apache 2.0\n\u002F\u002F @license.url   http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0.html\n\n\u002F\u002F @host      localhost:8080\n\u002F\u002F @BasePath  \u002Fapi\u002Fv1\n\n\u002F\u002F @securityDefinitions.basic  BasicAuth\n\n\u002F\u002F @externalDocs.description  OpenAPI\n\u002F\u002F @externalDocs.url          https:\u002F\u002Fswagger.io\u002Fresources\u002Fopen-api\u002F\nfunc main() {\n\tr := gin.Default()\n\n\tc := controller.NewController()\n\n\tv1 := r.Group(\"\u002Fapi\u002Fv1\")\n\t{\n\t\taccounts := v1.Group(\"\u002Faccounts\")\n\t\t{\n\t\t\taccounts.GET(\":id\", c.ShowAccount)\n\t\t\taccounts.GET(\"\", c.ListAccounts)\n\t\t\taccounts.POST(\"\", c.AddAccount)\n\t\t\taccounts.DELETE(\":id\", c.DeleteAccount)\n\t\t\taccounts.PATCH(\":id\", c.UpdateAccount)\n\t\t\taccounts.POST(\":id\u002Fimages\", c.UploadAccountImage)\n\t\t}\n    \u002F\u002F...\n\t}\n\tr.GET(\"\u002Fswagger\u002F*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n\tr.Run(\":8080\")\n}\n\u002F\u002F...\n```\n\nAdditionally 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:\n\n```go\npackage main\n\nimport (\n\t\"github.com\u002Fgin-gonic\u002Fgin\"\n\t\"github.com\u002Fswaggo\u002Ffiles\"\n\t\"github.com\u002Fswaggo\u002Fgin-swagger\"\n\n\t\".\u002Fdocs\" \u002F\u002F docs is generated by Swag CLI, you have to import it.\n)\n\n\u002F\u002F @contact.name   API Support\n\u002F\u002F @contact.url    http:\u002F\u002Fwww.swagger.io\u002Fsupport\n\u002F\u002F @contact.email  support@swagger.io\n\n\u002F\u002F @license.name  Apache 2.0\n\u002F\u002F @license.url   http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0.html\nfunc main() {\n\n\t\u002F\u002F programmatically set swagger info\n\tdocs.SwaggerInfo.Title = \"Swagger Example API\"\n\tdocs.SwaggerInfo.Description = \"This is a sample server Petstore server.\"\n\tdocs.SwaggerInfo.Version = \"1.0\"\n\tdocs.SwaggerInfo.Host = \"petstore.swagger.io\"\n\tdocs.SwaggerInfo.BasePath = \"\u002Fv2\"\n\tdocs.SwaggerInfo.Schemes = []string{\"http\", \"https\"}\n\n\tr := gin.New()\n\n\t\u002F\u002F use ginSwagger middleware to serve the API docs\n\tr.GET(\"\u002Fswagger\u002F*any\", ginSwagger.WrapHandler(swaggerFiles.Handler))\n\n\tr.Run()\n}\n```\n\n3. Add [API Operation](#api-operation) annotations in `controller` code\n\n``` go\npackage controller\n\nimport (\n    \"fmt\"\n    \"net\u002Fhttp\"\n    \"strconv\"\n\n    \"github.com\u002Fgin-gonic\u002Fgin\"\n    \"github.com\u002Fswaggo\u002Fswag\u002Fexample\u002Fceller\u002Fhttputil\"\n    \"github.com\u002Fswaggo\u002Fswag\u002Fexample\u002Fceller\u002Fmodel\"\n)\n\n\u002F\u002F ShowAccount godoc\n\u002F\u002F @Summary      Show an account\n\u002F\u002F @Description  get string by ID\n\u002F\u002F @Tags         accounts\n\u002F\u002F @Accept       json\n\u002F\u002F @Produce      json\n\u002F\u002F @Param        id   path      int  true  \"Account ID\"\n\u002F\u002F @Success      200  {object}  model.Account\n\u002F\u002F @Failure      400  {object}  httputil.HTTPError\n\u002F\u002F @Failure      404  {object}  httputil.HTTPError\n\u002F\u002F @Failure      500  {object}  httputil.HTTPError\n\u002F\u002F @Router       \u002Faccounts\u002F{id} [get]\nfunc (c *Controller) ShowAccount(ctx *gin.Context) {\n  id := ctx.Param(\"id\")\n  aid, err := strconv.Atoi(id)\n  if err != nil {\n    httputil.NewError(ctx, http.StatusBadRequest, err)\n    return\n  }\n  account, err := model.AccountOne(aid)\n  if err != nil {\n    httputil.NewError(ctx, http.StatusNotFound, err)\n    return\n  }\n  ctx.JSON(http.StatusOK, account)\n}\n\n\u002F\u002F ListAccounts godoc\n\u002F\u002F @Summary      List accounts\n\u002F\u002F @Description  get accounts\n\u002F\u002F @Tags         accounts\n\u002F\u002F @Accept       json\n\u002F\u002F @Produce      json\n\u002F\u002F @Param        q    query     string  false  \"name search by q\"  Format(email)\n\u002F\u002F @Success      200  {array}   model.Account\n\u002F\u002F @Failure      400  {object}  httputil.HTTPError\n\u002F\u002F @Failure      404  {object}  httputil.HTTPError\n\u002F\u002F @Failure      500  {object}  httputil.HTTPError\n\u002F\u002F @Router       \u002Faccounts [get]\nfunc (c *Controller) ListAccounts(ctx *gin.Context) {\n  q := ctx.Request.URL.Query().Get(\"q\")\n  accounts, err := model.AccountsAll(q)\n  if err != nil {\n    httputil.NewError(ctx, http.StatusNotFound, err)\n    return\n  }\n  ctx.JSON(http.StatusOK, accounts)\n}\n\u002F\u002F...\n```\n\n```console\nswag init\n```\n\n4. Run your app, and browse to http:\u002F\u002Flocalhost:8080\u002Fswagger\u002Findex.html. You will see Swagger 2.0 Api documents as shown below:\n\n![swagger_index.html](https:\u002F\u002Fraw.githubusercontent.com\u002Fswaggo\u002Fswag\u002Fmaster\u002Fassets\u002Fswagger-image.png)\n\n## The swag formatter\n\nThe Swag Comments can be automatically formatted, just like 'go fmt'.\nFind the result of formatting [here](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Ftree\u002Fmaster\u002Fexample\u002Fceller).\n\nUsage:\n```shell\nswag fmt\n```\n\nExclude folder：\n```shell\nswag fmt -d .\u002F --exclude .\u002Finternal\n```\n\nWhen using `swag fmt`, you need to ensure that you have a doc comment for the function to ensure correct formatting.\nThis is due to `swag fmt` indenting swag comments with tabs, which is only allowed *after* a standard doc comment.\n\nFor example, use\n\n```go\n\u002F\u002F ListAccounts lists all existing accounts\n\u002F\u002F\n\u002F\u002F  @Summary      List accounts\n\u002F\u002F  @Description  get accounts\n\u002F\u002F  @Tags         accounts\n\u002F\u002F  @Accept       json\n\u002F\u002F  @Produce      json\n\u002F\u002F  @Param        q    query     string  false  \"name search by q\"  Format(email)\n\u002F\u002F  @Success      200  {array}   model.Account\n\u002F\u002F  @Failure      400  {object}  httputil.HTTPError\n\u002F\u002F  @Failure      404  {object}  httputil.HTTPError\n\u002F\u002F  @Failure      500  {object}  httputil.HTTPError\n\u002F\u002F  @Router       \u002Faccounts [get]\nfunc (c *Controller) ListAccounts(ctx *gin.Context) {\n```\n\n## Implementation Status\n\n[Swagger 2.0 document](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002F2-0\u002Fbasic-structure\u002F)\n\n- [x] Basic Structure\n- [x] API Host and Base Path\n- [x] Paths and Operations\n- [x] Describing Parameters\n- [x] Describing Request Body\n- [x] Describing Responses\n- [x] MIME Types\n- [x] Authentication\n  - [x] Basic Authentication\n  - [x] API Keys\n- [x] Adding Examples\n- [x] File Upload\n- [x] Enums\n- [x] Grouping Operations With Tags\n- [ ] Swagger Extensions\n\n# Declarative Comments Format\n\n## General API Info\n\n**Example**\n[celler\u002Fmain.go](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fblob\u002Fmaster\u002Fexample\u002Fceller\u002Fmain.go)\n\n| annotation  | description                                | example                         |\n|-------------|--------------------------------------------|---------------------------------|\n| title       | **Required.** The title of the application.| \u002F\u002F @title Swagger Example API   |\n| version     | **Required.** Provides the version of the application API.| \u002F\u002F @version 1.0  |\n| description | A short description of the application.    |\u002F\u002F @description This is a sample server celler server.         \t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t |\n| tag.name    | Name of a tag.| \u002F\u002F @tag.name This is the name of the tag                     |\n| tag.description   | Description of the tag  | \u002F\u002F @tag.description Cool Description         |\n| tag.docs.url      | Url of the external Documentation of the tag | \u002F\u002F @tag.docs.url https:\u002F\u002Fexample.com|\n| tag.docs.description  | Description of the external Documentation of the tag| \u002F\u002F @tag.docs.description Best example documentation |\n| termsOfService | The Terms of Service for the API.| \u002F\u002F @termsOfService http:\u002F\u002Fswagger.io\u002Fterms\u002F                     |\n| contact.name | The contact information for the exposed API.| \u002F\u002F @contact.name API Support  |\n| contact.url  | The URL pointing to the contact information. MUST be in the format of a URL.  | \u002F\u002F @contact.url http:\u002F\u002Fwww.swagger.io\u002Fsupport|\n| contact.email| The email address of the contact person\u002Forganization. MUST be in the format of an email address.| \u002F\u002F @contact.email support@swagger.io                                   |\n| license.name | **Required.** The license name used for the API.|\u002F\u002F @license.name Apache 2.0|\n| license.url  | A URL to the license used for the API. MUST be in the format of a URL.                       | \u002F\u002F @license.url http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0.html |\n| host        | The host (name or ip) serving the API.     | \u002F\u002F @host localhost:8080         |\n| BasePath    | The base path on which the API is served. | \u002F\u002F @BasePath \u002Fapi\u002Fv1             |\n| 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).                     | \u002F\u002F @accept json |\n| produce     | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types).                     | \u002F\u002F @produce json |\n| query.collection.format | The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default.| \u002F\u002F @query.collection.format multi\n| schemes     | The transfer protocol for the operation that separated by spaces. | \u002F\u002F @schemes http https |\n| externalDocs.description | Description of the external document. | \u002F\u002F @externalDocs.description OpenAPI |\n| externalDocs.url         | URL of the external document. | \u002F\u002F @externalDocs.url https:\u002F\u002Fswagger.io\u002Fresources\u002Fopen-api\u002F |\n| x-name      | The extension key, must be start by x- and take only json value | \u002F\u002F @x-example-key {\"key\": \"value\"} |\n\n### Using markdown descriptions\nWhen 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.\n\n\n| annotation  | description                                | example                         |\n|-------------|--------------------------------------------|---------------------------------|\n| title       | **Required.** The title of the application.| \u002F\u002F @title Swagger Example API   |\n| version     | **Required.** Provides the version of the application API.| \u002F\u002F @version 1.0  |\n| description.markdown  | A short description of the application. Parsed from the api.md file. This is an alternative to @description    |\u002F\u002F @description.markdown No value needed, this parses the description from api.md         \t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t |\n| tag.name    | Name of a tag.| \u002F\u002F @tag.name This is the name of the tag                     |\n| 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  | \u002F\u002F @tag.description.markdown         |\n| tag.x-name  | The extension key, must be start by x- and take only string value | \u002F\u002F @x-example-key value |\n\n\n## API Operation\n\n**Example**\n[celler\u002Fcontroller](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Ftree\u002Fmaster\u002Fexample\u002Fceller\u002Fcontroller)\n\n\n| annotation           | description                                                                                                                                                                                       |\n|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| description          | A verbose explanation of the operation behavior.                                                                                                                                                  |\n| 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`                                                    | \u002F\u002F @description.file endpoint.description.markdown  |\n| id                   | A unique string used to identify the operation. Must be unique among all API operations.                                                                                                          |\n| tags                 | A list of tags to each API operation that separated by commas.                                                                                                                                    |\n| summary              | A short summary of what the operation does.                                                                                                                                                       |\n| 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). |\n| produce              | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types).                                                                                            |\n| param                | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)`                                                                        |\n| security             | [Security](#security) to each API operation.                                                                                                                                                      |\n| success              | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`                                                                                          |\n| failure              | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`                                                                                          |\n| response             | As same as `success` and `failure`                                                                                                                                                                |\n| header               | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment`                                                                                                   |\n| router               | Path definition that separated by spaces. `path`,`[httpMethod]`                                                                                                                                   |\n| deprecatedrouter     | As same as router, but deprecated.                                                                                                                                                     |\n| x-name               | The extension key, must be start by x- and take only json value.                                                                                                                                  |\n| x-codeSample         | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder.                                                                   |\n| deprecated           | Mark endpoint as deprecated.                                                                                                                                                                      |\n\n\n\n## Mime Types\n\n`swag` accepts all MIME Types which are in the correct format, that is, match `*\u002F*`.\nBesides that, `swag` also accepts aliases for some MIME Types as follows:\n\n| Alias                 | MIME Type                         |\n|-----------------------|-----------------------------------|\n| json                  | application\u002Fjson                  |\n| xml                   | text\u002Fxml                          |\n| plain                 | text\u002Fplain                        |\n| html                  | text\u002Fhtml                         |\n| mpfd                  | multipart\u002Fform-data               |\n| x-www-form-urlencoded | application\u002Fx-www-form-urlencoded |\n| json-api              | application\u002Fvnd.api+json          |\n| json-stream           | application\u002Fx-json-stream         |\n| octet-stream          | application\u002Foctet-stream          |\n| png                   | image\u002Fpng                         |\n| jpeg                  | image\u002Fjpeg                        |\n| gif                   | image\u002Fgif                         |\n| event-stream          | text\u002Fevent-stream                 |\n\n\n\n## Param Type\n\n- query\n- path\n- header\n- body\n- formData\n\n## Data Type\n\n- string (string)\n- integer (int, uint, uint32, uint64)\n- number (float32)\n- boolean (bool)\n- file (param data type when uploading)\n- user defined struct\n\n## Security\n| annotation | description | parameters | example |\n|------------|-------------|------------|---------|\n| securitydefinitions.basic  | [Basic](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002F2-0\u002Fauthentication\u002Fbasic-authentication\u002F) auth.  |                                   | \u002F\u002F @securityDefinitions.basic BasicAuth                      |\n| securitydefinitions.apikey | [API key](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002F2-0\u002Fauthentication\u002Fapi-keys\u002F) auth.            | in, name, description                          | \u002F\u002F @securityDefinitions.apikey ApiKeyAuth                    |\n| securitydefinitions.oauth2.application  | [OAuth2 application](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fauthentication\u002Foauth2\u002F) auth.       | tokenUrl, scope, description                   | \u002F\u002F @securitydefinitions.oauth2.application OAuth2Application |\n| securitydefinitions.oauth2.implicit     | [OAuth2 implicit](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fauthentication\u002Foauth2\u002F) auth.          | authorizationUrl, scope, description           | \u002F\u002F @securitydefinitions.oauth2.implicit OAuth2Implicit       |\n| securitydefinitions.oauth2.password     | [OAuth2 password](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fauthentication\u002Foauth2\u002F) auth.          | tokenUrl, scope, description                   | \u002F\u002F @securitydefinitions.oauth2.password OAuth2Password       |\n| securitydefinitions.oauth2.accessCode   | [OAuth2 access code](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fauthentication\u002Foauth2\u002F) auth.       | tokenUrl, authorizationUrl, scope, description | \u002F\u002F @securitydefinitions.oauth2.accessCode OAuth2AccessCode   |\n\n\n| parameters annotation           | example                                                                 |\n|---------------------------------|-------------------------------------------------------------------------|\n| in                              | \u002F\u002F @in header                                                           |\n| name                            | \u002F\u002F @name Authorization                                                  |\n| tokenUrl                        | \u002F\u002F @tokenUrl https:\u002F\u002Fexample.com\u002Foauth\u002Ftoken                            |\n| authorizationurl                | \u002F\u002F @authorizationurl https:\u002F\u002Fexample.com\u002Foauth\u002Fauthorize                |\n| scope.hoge                      | \u002F\u002F @scope.write Grants write access                                     |\n| description                     | \u002F\u002F @description OAuth protects our entity endpoints                     |\n\n## Attribute\n\n```go\n\u002F\u002F @Param   enumstring  query     string     false  \"string enums\"       Enums(A, B, C)\n\u002F\u002F @Param   enumint     query     int        false  \"int enums\"          Enums(1, 2, 3)\n\u002F\u002F @Param   enumnumber  query     number     false  \"int enums\"          Enums(1.1, 1.2, 1.3)\n\u002F\u002F @Param   string      query     string     false  \"string valid\"       minlength(5)  maxlength(10)\n\u002F\u002F @Param   int         query     int        false  \"int valid\"          minimum(1)    maximum(10)\n\u002F\u002F @Param   default     query     string     false  \"string default\"     default(A)\n\u002F\u002F @Param   example     query     string     false  \"string example\"     example(string)\n\u002F\u002F @Param   collection  query     []string   false  \"string collection\"  collectionFormat(multi)\n\u002F\u002F @Param   extensions  query     []string   false  \"string collection\"  extensions(x-example=test,x-nullable)\n```\n\nIt also works for the struct fields:\n\n```go\ntype Foo struct {\n    Bar string `minLength:\"4\" maxLength:\"16\" example:\"random string\"`\n    Baz int `minimum:\"10\" maximum:\"20\" default:\"15\"`\n    Qux []string `enums:\"foo,bar,baz\"`\n}\n```\n\n### Available\n\nField Name | Type | Description\n---|:---:|---\n\u003Ca name=\"validate\">\u003C\u002Fa>validate | `string` | \tDetermines the validation for the parameter. Possible values are: `required,optional`.\n\u003Ca name=\"json\">\u003C\u002Fa>json | `string` | JSON tag options. The `omitempty` option will mark the field as not required.\n\u003Ca name=\"parameterDefault\">\u003C\u002Fa>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:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter.\n\u003Ca name=\"parameterMaximum\">\u003C\u002Fa>maximum | `number` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.1.2.\n\u003Ca name=\"parameterMinimum\">\u003C\u002Fa>minimum | `number` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.1.3.\n\u003Ca name=\"parameterMultipleOf\">\u003C\u002Fa>multipleOf | `number` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.1.1.\n\u003Ca name=\"parameterMaxLength\">\u003C\u002Fa>maxLength | `integer` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.2.1.\n\u003Ca name=\"parameterMinLength\">\u003C\u002Fa>minLength | `integer` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.2.2.\n\u003Ca name=\"parameterEnums\">\u003C\u002Fa>enums | [\\*] | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.5.1.\n\u003Ca name=\"parameterFormat\">\u003C\u002Fa>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](https:\u002F\u002Fswagger.io\u002Fspecification\u002Fv2\u002F#dataTypeFormat) for further details.\n\u003Ca name=\"parameterCollectionFormat\">\u003C\u002Fa>collectionFormat | `string` |Determines the format of the array if type array is used. Possible values are: \u003Cul>\u003Cli>`csv` - comma separated values `foo,bar`. \u003Cli>`ssv` - space separated values `foo bar`. \u003Cli>`tsv` - tab separated values `foo\\tbar`. \u003Cli>`pipes` - pipe separated values \u003Ccode>foo|bar\u003C\u002Fcode>. \u003Cli>`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\". \u003C\u002Ful> Default value is `csv`.\n\u003Ca name=\"parameterExample\">\u003C\u002Fa>example | * | Declares the example for the parameter value\n\u003Ca name=\"parameterExtensions\">\u003C\u002Fa>extensions | `string` | Add extension to parameters.\n\n### Future\n\nField Name | Type | Description\n---|:---:|---\n\u003Ca name=\"parameterPattern\">\u003C\u002Fa>pattern | `string` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.2.3.\n\u003Ca name=\"parameterMaxItems\">\u003C\u002Fa>maxItems | `integer` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.3.2.\n\u003Ca name=\"parameterMinItems\">\u003C\u002Fa>minItems | `integer` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.3.3.\n\u003Ca name=\"parameterUniqueItems\">\u003C\u002Fa>uniqueItems | `boolean` | See https:\u002F\u002Ftools.ietf.org\u002Fhtml\u002Fdraft-fge-json-schema-validation-00#section-5.3.4.\n\n## Examples\n\n### Descriptions over multiple lines\n\nYou can add descriptions spanning multiple lines in either the general api description or routes definitions like so:\n\n```go\n\u002F\u002F @description This is the first line\n\u002F\u002F @description This is the second line\n\u002F\u002F @description And so forth.\n```\n\n### User defined structure with an array type\n\n```go\n\u002F\u002F @Success 200 {array} model.Account \u003C-- This is a user defined struct.\n```\n\n```go\npackage model\n\ntype Account struct {\n    ID   int    `json:\"id\" example:\"1\"`\n    Name string `json:\"name\" example:\"account name\"`\n}\n```\n\n\n### Function scoped struct declaration\n\nYou can declare your request response structs inside a function body.\nYou must have to follow the naming convention `\u003Cpackage-name>.\u003Cfunction-name>.\u003Cstruct-name> `.\n\n```go\npackage main\n\n\u002F\u002F @Param request body main.MyHandler.request true \"query params\"\n\u002F\u002F @Success 200 {object} main.MyHandler.response\n\u002F\u002F @Router \u002Ftest [post]\nfunc MyHandler() {\n\ttype request struct {\n\t\tRequestField string\n\t}\n\n\ttype response struct {\n\t\tResponseField string\n\t}\n}\n```\n\n\n### Model composition in response\n```go\n\u002F\u002F JSONResult's data field will be overridden by the specific type proto.Order\n@success 200 {object} jsonresult.JSONResult{data=proto.Order} \"desc\"\n```\n\n```go\ntype JSONResult struct {\n    Code    int          `json:\"code\" `\n    Message string       `json:\"message\"`\n    Data    interface{}  `json:\"data\"`\n}\n\ntype Order struct { \u002F\u002Fin `proto` package\n    Id  uint            `json:\"id\"`\n    Data  interface{}   `json:\"data\"`\n}\n```\n\n- also support array of objects and primitive types as nested response\n```go\n@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} \"desc\"\n@success 200 {object} jsonresult.JSONResult{data=string} \"desc\"\n@success 200 {object} jsonresult.JSONResult{data=[]string} \"desc\"\n```\n\n- overriding multiple fields. field will be added if not exists\n```go\n@success 200 {object} jsonresult.JSONResult{data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} \"desc\"\n```\n- overriding deep-level fields\n```go\ntype DeepObject struct { \u002F\u002Fin `proto` package\n\t...\n}\n@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} \"desc\"\n```\n### Add request headers\n\n```go\n\u002F\u002F @Param        X-MyHeader\t  header    string    true   \t\"MyHeader must be set for valid response\"\n\u002F\u002F @Param        X-API-VERSION    header    string    true   \t\"API version eg.: 1.0\"\n```\n\n### Add response headers\n\n```go\n\u002F\u002F @Success      200              {string}  string    \"ok\"\n\u002F\u002F @failure      400              {string}  string    \"error\"\n\u002F\u002F @response     default          {string}  string    \"other error\"\n\u002F\u002F @Header       200              {string}  Location  \"\u002Fentity\u002F1\"\n\u002F\u002F @Header       200,400,default  {string}  Token     \"token\"\n\u002F\u002F @Header       all              {string}  Token2    \"token2\"\n```\n\n### Use multiple path params\n\n```go\n\u002F\u002F\u002F ...\n\u002F\u002F @Param group_id   path int true \"Group ID\"\n\u002F\u002F @Param account_id path int true \"Account ID\"\n\u002F\u002F ...\n\u002F\u002F @Router \u002Fexamples\u002Fgroups\u002F{group_id}\u002Faccounts\u002F{account_id} [get]\n```\n\n### Add multiple paths\n\n```go\n\u002F\u002F\u002F ...\n\u002F\u002F @Param group_id path int true \"Group ID\"\n\u002F\u002F @Param user_id  path int true \"User ID\"\n\u002F\u002F ...\n\u002F\u002F @Router \u002Fexamples\u002Fgroups\u002F{group_id}\u002Fuser\u002F{user_id}\u002Faddress [put]\n\u002F\u002F @Router \u002Fexamples\u002Fuser\u002F{user_id}\u002Faddress [put]\n```\n\n### Example value of struct\n\n```go\ntype Account struct {\n    ID   int    `json:\"id\" example:\"1\"`\n    Name string `json:\"name\" example:\"account name\"`\n    PhotoUrls []string `json:\"photo_urls\" example:\"http:\u002F\u002Ftest\u002Fimage\u002F1.jpg,http:\u002F\u002Ftest\u002Fimage\u002F2.jpg\"`\n}\n```\n\n### SchemaExample of body\n\n```go\n\u002F\u002F @Param email body string true \"message\u002Frfc822\" SchemaExample(Subject: Testmail\\r\\n\\r\\nBody Message\\r\\n)\n```\n\n### Description of struct\n\n```go\n\u002F\u002F Account model info\n\u002F\u002F @Description User account information\n\u002F\u002F @Description with user id and username\ntype Account struct {\n\t\u002F\u002F ID this is userid\n\tID   int    `json:\"id\"`\n\tName string `json:\"name\"` \u002F\u002F This is Name\n}\n```\n\n[#708](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fissues\u002F708) The parser handles only struct comments starting with `@Description` attribute.\nBut it writes all struct field comments as is.\n\nSo, generated swagger doc as follows:\n```json\n\"Account\": {\n  \"type\":\"object\",\n  \"description\": \"User account information with user id and username\"\n  \"properties\": {\n    \"id\": {\n      \"type\": \"integer\",\n      \"description\": \"ID this is userid\"\n    },\n    \"name\": {\n      \"type\":\"string\",\n      \"description\": \"This is Name\"\n    }\n  }\n}\n```\n\n### Use swaggertype tag to supported custom type\n[#201](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fissues\u002F201#issuecomment-475479409)\n\n```go\ntype TimestampTime struct {\n    time.Time\n}\n\n\u002F\u002F\u002Fimplement encoding.JSON.Marshaler interface\nfunc (t *TimestampTime) MarshalJSON() ([]byte, error) {\n    bin := make([]byte, 16)\n    bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)\n    return bin, nil\n}\n\nfunc (t *TimestampTime) UnmarshalJSON(bin []byte) error {\n    v, err := strconv.ParseInt(string(bin), 10, 64)\n    if err != nil {\n        return err\n    }\n    t.Time = time.Unix(v, 0)\n    return nil\n}\n\u002F\u002F\u002F\n\ntype Account struct {\n    \u002F\u002F Override primitive type by simply specifying it via `swaggertype` tag\n    ID     sql.NullInt64 `json:\"id\" swaggertype:\"integer\"`\n\n    \u002F\u002F Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag\n    RegisterTime TimestampTime `json:\"register_time\" swaggertype:\"primitive,integer\"`\n\n    \u002F\u002F Array types can be overridden using \"array,\u003Cprim_type>\" format\n    Coeffs []big.Float `json:\"coeffs\" swaggertype:\"array,number\"`\n}\n```\n\n[#379](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fissues\u002F379)\n```go\ntype CerticateKeyPair struct {\n\tCrt []byte `json:\"crt\" swaggertype:\"string\" format:\"base64\" example:\"U3dhZ2dlciByb2Nrcw==\"`\n\tKey []byte `json:\"key\" swaggertype:\"string\" format:\"base64\" example:\"U3dhZ2dlciByb2Nrcw==\"`\n}\n```\ngenerated swagger doc as follows:\n```go\n\"api.MyBinding\": {\n  \"type\":\"object\",\n  \"properties\":{\n    \"crt\":{\n      \"type\":\"string\",\n      \"format\":\"base64\",\n      \"example\":\"U3dhZ2dlciByb2Nrcw==\"\n    },\n    \"key\":{\n      \"type\":\"string\",\n      \"format\":\"base64\",\n      \"example\":\"U3dhZ2dlciByb2Nrcw==\"\n    }\n  }\n}\n\n```\n\n### Use global overrides to support a custom type\n\nIf you are using generated files, the [`swaggertype`](#use-swaggertype-tag-to-supported-custom-type) or `swaggerignore` tags may not be possible.\n\nBy 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.\n\nGo code:\n```go\ntype MyStruct struct {\n  ID     sql.NullInt64 `json:\"id\"`\n  Name   sql.NullString `json:\"name\"`\n}\n```\n\n`.swaggo`:\n```\n\u002F\u002F Replace all NullInt64 with int\nreplace database\u002Fsql.NullInt64 int\n\n\u002F\u002F Don't include any fields of type database\u002Fsql.NullString in the swagger docs\nskip    database\u002Fsql.NullString\n```\n\nPossible directives are comments (beginning with `\u002F\u002F`), `replace path\u002Fto\u002Fa.type path\u002Fto\u002Fb.type`, and `skip path\u002Fto\u002Fa.type`.\n\n(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)\n\nRendered:\n```go\n\"types.MyStruct\": {\n  \"id\": \"integer\"\n}\n```\n\n\n### Use swaggerignore tag to exclude a field\n\n```go\ntype Account struct {\n    ID   string    `json:\"id\"`\n    Name string     `json:\"name\"`\n    Ignored int     `swaggerignore:\"true\"`\n}\n```\n\n### Add extension info to struct field\n\n```go\ntype Account struct {\n    ID   string    `json:\"id\"   extensions:\"x-nullable,x-abc=def,!x-omitempty\"` \u002F\u002F extensions fields must start with \"x-\"\n}\n```\n\ngenerate swagger doc as follows:\n\n```go\n\"Account\": {\n    \"type\": \"object\",\n    \"properties\": {\n        \"id\": {\n            \"type\": \"string\",\n            \"x-nullable\": true,\n            \"x-abc\": \"def\",\n            \"x-omitempty\": false\n        }\n    }\n}\n```\n### Rename model to display\n\n```golang\ntype Resp struct {\n\tCode int\n}\u002F\u002F@name Response\n```\n\n### How to use security annotations\n\nGeneral API info.\n\n```go\n\u002F\u002F @securityDefinitions.basic BasicAuth\n\n\u002F\u002F @securitydefinitions.oauth2.application OAuth2Application\n\u002F\u002F @tokenUrl https:\u002F\u002Fexample.com\u002Foauth\u002Ftoken\n\u002F\u002F @scope.write Grants write access\n\u002F\u002F @scope.admin Grants read and write access to administrative information\n```\n\nEach API operation.\n\n```go\n\u002F\u002F @Security ApiKeyAuth\n```\n\nMake it OR condition\n\n```go\n\u002F\u002F @Security ApiKeyAuth\n\u002F\u002F @Security OAuth2Application[write, admin]\n```\n\nMake it AND condition\n\n```go\n\u002F\u002F @Security ApiKeyAuth && firebase\n\u002F\u002F @Security OAuth2Application[write, admin] && APIKeyAuth\n```\n\n### Generate enum types from enum constants\n\nYou 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.\n\n```go\ntype Difficulty string\n\nconst (\n\tEasy   Difficulty = \"easy\" \u002F\u002F You can add a comment to the enum variant.\n\tMedium Difficulty = \"medium\" \u002F\u002F @name MediumDifficulty\n\tHard   Difficulty = \"hard\" \u002F\u002F @name HardDifficulty You can have a name override and a comment.\n)\n\ntype Class int\n\nconst (\n\tFirst Class = iota \u002F\u002F @name FirstClass\n\tSecond \u002F\u002F Name override and comment rules apply here just as above.\n\tThird \u002F\u002F @name ThirdClass This one has a name override and a comment.\n)\n\n\u002F\u002F There is no need to add `enums:\"...\"` to the fields, it is automatically generated from the ordered consts.\ntype Quiz struct {\n\tDifficulty Difficulty\n\tClass Class\n\tQuestions []string\n\tAnswers []string\n}\n```\n\n\n### Add a description for enum items\n\n```go\ntype Example struct {\n\t\u002F\u002F Sort order:\n\t\u002F\u002F * asc - Ascending, from A to Z.\n\t\u002F\u002F * desc - Descending, from Z to A.\n\tOrder string `enums:\"asc,desc\"`\n}\n```\n\n### Generate only specific docs file types\n\nBy default `swag` command generates Swagger specification in three different files\u002Ffile types:\n- docs.go\n- swagger.json\n- swagger.yaml\n\nIf 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`.\n\n### How to use Generics\n\n```go\n\u002F\u002F @Success 200 {object} web.GenericNestedResponse[types.Post]\n\u002F\u002F @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]\n\u002F\u002F @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]\nfunc GetPosts(w http.ResponseWriter, r *http.Request) {\n\t_ = web.GenericNestedResponse[types.Post]{}\n}\n```\nSee [this file](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fblob\u002Fmaster\u002Ftestdata\u002Fgenerics_nested\u002Fapi\u002Fapi.go) for more details\nand other examples.\n\n### Change the default Go Template action delimiters\n[#980](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fissues\u002F980)\n[#1177](https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fissues\u002F1177)\n\nIf 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:\u002F\u002Fpkg.go.dev\u002Ftext\u002Ftemplate#Template.Delims).\n\nTo make the generation work properly, you can change the default delimiters with `-td`. For example:\n```console\nswag init -g http\u002Fapi.go -td \"[[,]]\"\n```\nThe new delimiter is a string with the format \"`\u003Cleft delimiter>`,`\u003Cright delimiter>`\".\n\n### Parse Internal and Dependency Packages\n\nIf the struct is defined in a dependency package, use `--parseDependency`.\n\nIf the struct is defined in your main project, use `--parseInternal`.\n\nif you want to include both internal and from dependencies use both flags\n```\nswag init --parseDependency --parseInternal\n```\n\n## About the Project\nThis project was inspired by [yvasiyarov\u002Fswagger](https:\u002F\u002Fgithub.com\u002Fyvasiyarov\u002Fswagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn\u002Fgopher-stickers](https:\u002F\u002Fgithub.com\u002Ftenntenn\u002Fgopher-stickers). It has licenses [creative commons licensing](http:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby\u002F3.0\u002Fdeed.en).\n## Contributors\n\nThis project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fgraphs\u002Fcontributors\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fcontributors.svg?width=890&button=false\" \u002F>\u003C\u002Fa>\n\n\n## Backers\n\nThank you to all our backers! 🙏 [[Become a backer](https:\u002F\u002Fopencollective.com\u002Fswag#backer)]\n\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag#backers\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fbackers.svg?width=890\">\u003C\u002Fa>\n\n\n## Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https:\u002F\u002Fopencollective.com\u002Fswag#sponsor)]\n\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F0\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F0\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F1\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F1\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F2\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F2\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F3\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F3\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F4\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F4\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F5\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F5\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F6\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F6\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F7\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F7\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F8\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F8\u002Favatar.svg\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F9\u002Fwebsite\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Fopencollective.com\u002Fswag\u002Fsponsor\u002F9\u002Favatar.svg\">\u003C\u002Fa>\n\n\n\n\n## License\n[![FOSSA Status](https:\u002F\u002Fapp.fossa.io\u002Fapi\u002Fprojects\u002Fgit%2Bgithub.com%2Fswaggo%2Fswag.svg?type=large)](https:\u002F\u002Fapp.fossa.io\u002Fprojects\u002Fgit%2Bgithub.com%2Fswaggo%2Fswag?ref=badge_large)\n","swaggo\u002Fswag 是一个用于自动生成 Go 语言 RESTful API 的 Swagger 2.0 文档的工具。它通过解析 Go 代码中的注解来生成详细的 API 文档，支持多种主流的 Go Web 框架，如 Gin、Echo 等，从而能够轻松地与现有的 Go 项目集成。其核心功能包括自动化文档生成、丰富的注解支持（如安全声明、请求头和响应头等）以及模型组合等功能。适用于需要快速生成并维护 API 文档的 Go 开发者或团队，尤其是在构建微服务架构时，能够显著提高开发效率和文档的一致性。","2026-06-11 03:01:47","top_language"]