{"id":13562475,"url":"https://github.com/swaggo/gin-swagger","last_synced_at":"2025-04-23T20:59:15.294Z","repository":{"id":37660667,"uuid":"95058978","full_name":"swaggo/gin-swagger","owner":"swaggo","description":"gin middleware to automatically generate RESTful API documentation with Swagger 2.0.","archived":false,"fork":false,"pushed_at":"2024-12-02T21:44:47.000Z","size":12415,"stargazers_count":3961,"open_issues_count":110,"forks_count":281,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-23T20:59:10.646Z","etag":null,"topics":["gin","gin-middleware","gin-swagger","golang","middleware","swagger"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swaggo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-22T00:45:54.000Z","updated_at":"2025-04-23T16:44:00.000Z","dependencies_parsed_at":"2024-01-23T21:17:26.772Z","dependency_job_id":"31117da7-6373-44e6-b29c-e1dba25c93ed","html_url":"https://github.com/swaggo/gin-swagger","commit_stats":{"total_commits":95,"total_committers":40,"mean_commits":2.375,"dds":0.6631578947368422,"last_synced_commit":"aa92a0ac3f26c587e4248afcf8d8b6318353e7b0"},"previous_names":["swag-gonic/gin-swagger"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fgin-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fgin-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fgin-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fgin-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggo","download_url":"https://codeload.github.com/swaggo/gin-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514767,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gin","gin-middleware","gin-swagger","golang","middleware","swagger"],"created_at":"2024-08-01T13:01:09.052Z","updated_at":"2025-04-23T20:59:15.279Z","avatar_url":"https://github.com/swaggo.png","language":"Go","funding_links":[],"categories":["开源类库","Go","Web","Open source library","Middlewares","开发工具\u0026框架"],"sub_categories":["文档","Documentation"],"readme":"# gin-swagger\n\ngin middleware to automatically generate RESTful API documentation with Swagger 2.0.\n\n[![Build Status](https://github.com/swaggo/gin-swagger/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/features/actions)\n[![Codecov branch](https://img.shields.io/codecov/c/github/swaggo/gin-swagger/master.svg)](https://codecov.io/gh/swaggo/gin-swagger)\n[![Go Report Card](https://goreportcard.com/badge/github.com/swaggo/gin-swagger)](https://goreportcard.com/report/github.com/swaggo/gin-swagger)\n[![GoDoc](https://godoc.org/github.com/swaggo/gin-swagger?status.svg)](https://godoc.org/github.com/swaggo/gin-swagger)\n[![Release](https://img.shields.io/github/release/swaggo/gin-swagger.svg?style=flat-square)](https://github.com/swaggo/gin-swagger/releases)\n\n## Usage\n\n### Start using it\n\n1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format).\n2. Download [Swag](https://github.com/swaggo/swag) for Go by using:\n\n```sh\ngo get -u github.com/swaggo/swag/cmd/swag\n```\n\nStarting in Go 1.17, installing executables with `go get` is deprecated. `go install` may be used instead:\n\n```sh\ngo install github.com/swaggo/swag/cmd/swag@latest\n```\n\n3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-project-name`),\n   [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`)\n   at `~/root/go-project-name/docs`.\n\n```sh\nswag init\n```\n\n4. Download [gin-swagger](https://github.com/swaggo/gin-swagger) by using:\n\n```sh\ngo get -u github.com/swaggo/gin-swagger\ngo get -u github.com/swaggo/files\n```\n\nImport following in your code:\n\n```go\nimport \"github.com/swaggo/gin-swagger\" // gin-swagger middleware\nimport \"github.com/swaggo/files\" // swagger embed files\n\n```\n\n### Canonical example:\n\nNow assume you have implemented a simple api as following:\n\n```go\n// A get function which returns a hello world string by json\nfunc Helloworld(g *gin.Context)  {\n\tg.JSON(http.StatusOK,\"helloworld\")\n}\n\n```\n\nSo how to use gin-swagger on api above? Just follow the following guide.\n\n1. Add Comments for apis and main function with gin-swagger rules like following:\n\n```go\n// @BasePath /api/v1\n\n// PingExample godoc\n// @Summary ping example\n// @Schemes\n// @Description do ping\n// @Tags example\n// @Accept json\n// @Produce json\n// @Success 200 {string} Helloworld\n// @Router /example/helloworld [get]\nfunc Helloworld(g *gin.Context)  {\n\tg.JSON(http.StatusOK,\"helloworld\")\n}\n```\n\n2. Use `swag init` command to generate a docs, docs generated will be stored at `docs/`.\n3. import the docs like this:\n   I assume your project named `github.com/go-project-name/docs`.\n\n```go\nimport (\n   docs \"github.com/go-project-name/docs\"\n)\n```\n\n4. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI.\n\n5. The full code and folder relatives here:\n\n```go\npackage main\n\nimport (\n   \"github.com/gin-gonic/gin\"\n   docs \"github.com/go-project-name/docs\"\n   swaggerfiles \"github.com/swaggo/files\"\n   ginSwagger \"github.com/swaggo/gin-swagger\"\n   \"net/http\"\n)\n// @BasePath /api/v1\n\n// PingExample godoc\n// @Summary ping example\n// @Schemes\n// @Description do ping\n// @Tags example\n// @Accept json\n// @Produce json\n// @Success 200 {string} Helloworld\n// @Router /example/helloworld [get]\nfunc Helloworld(g *gin.Context)  {\n   g.JSON(http.StatusOK,\"helloworld\")\n}\n\nfunc main()  {\n   r := gin.Default()\n   docs.SwaggerInfo.BasePath = \"/api/v1\"\n   v1 := r.Group(\"/api/v1\")\n   {\n      eg := v1.Group(\"/example\")\n      {\n         eg.GET(\"/helloworld\",Helloworld)\n      }\n   }\n   r.GET(\"/swagger/*any\", ginSwagger.WrapHandler(swaggerfiles.Handler))\n   r.Run(\":8080\")\n\n}\n```\n\nDemo project tree, `swag init` is run at relative `.`\n\n```\n.\n├── docs\n│   ├── docs.go\n│   ├── swagger.json\n│   └── swagger.yaml\n├── go.mod\n├── go.sum\n└── main.go\n```\n## Project with Nested Directory\n```\n.\n├── cmd\n│   └── ginsimple\n│       └── main.go\n├── docs\n│   ├── docs.go\n│   ├── swagger.json\n│   └── swagger.yaml\n├── go.mod\n├── go.sum\n└── internal\n    ├── handlers\n    │   ├── helloWorld.go\n    │   └── userHandler.go\n    └── models\n        ├── profile.go\n        └── user.go\n```\nInorder generate swagger docs for projects with nested directories run the following command\n```bash\nswag init -g ./cmd/ginsimple/main.go -o cmd/docs\n```\n`-o` will set the auto generated file to the specified path\n\n\n## Multiple APIs\n\nThis feature was introduced in swag v1.7.9\n\n## Configuration\n\nYou can configure Swagger using different configuration options\n\n```go\nfunc main() {\n\tr := gin.New()\n\n\tginSwagger.WrapHandler(swaggerfiles.Handler,\n\t\tginSwagger.URL(\"http://localhost:8080/swagger/doc.json\"),\n\t\tginSwagger.DefaultModelsExpandDepth(-1))\n\n\tr.Run()\n}\n```\n\n| Option                   | Type   | Default    | Description                                                                                                                                                                                                                                               |\n| ------------------------ | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| URL                      | string | \"doc.json\" | URL pointing to API definition                                                                                                                                                                                                                            |\n| DocExpansion             | string | \"list\"     | Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).                                                                       |\n| DeepLinking              | bool   | true       | If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.                                                                                                                                    |\n| DefaultModelsExpandDepth | int    | 1          | Default expansion depth for models (set to -1 completely hide the models).                                                                                                                                                                                |\n| InstanceName             | string | \"swagger\"  | The instance name of the swagger document. If multiple different swagger instances should be deployed on one gin router, ensure that each instance has a unique name (use the _--instanceName_ parameter to generate swagger documents with _swag init_). |\n| PersistAuthorization     | bool   | false      | If set to true, it persists authorization data and it would not be lost on browser close/refresh.                                                                                                                                                         |\n| Oauth2DefaultClientID    | string | \"\"         | If set, it's used to prepopulate the _client_id_ field of the OAuth2 Authorization dialog.                                                                                                                                                                |\n| Oauth2UsePkce            | bool   | false      | If set to true, it enables Proof Key for Code Exchange to enhance security for OAuth public clients.                                                                                                                                                      |","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggo%2Fgin-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggo%2Fgin-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggo%2Fgin-swagger/lists"}