{"id":15035428,"url":"https://github.com/swaggo/http-swagger","last_synced_at":"2025-05-15T09:07:51.527Z","repository":{"id":37270014,"uuid":"122907158","full_name":"swaggo/http-swagger","owner":"swaggo","description":"Default net/http wrapper to automatically generate RESTful API documentation with Swagger 2.0.","archived":false,"fork":false,"pushed_at":"2024-08-15T06:43:34.000Z","size":93,"stargazers_count":493,"open_issues_count":36,"forks_count":79,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-11T19:56:21.149Z","etag":null,"topics":["golang","middleware","swagger2"],"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":"2018-02-26T03:22:40.000Z","updated_at":"2025-04-10T06:33:15.000Z","dependencies_parsed_at":"2024-01-23T21:17:24.094Z","dependency_job_id":"1683c3d3-c90d-436a-8eab-f6d2217b9361","html_url":"https://github.com/swaggo/http-swagger","commit_stats":{"total_commits":68,"total_committers":18,"mean_commits":"3.7777777777777777","dds":0.5441176470588236,"last_synced_commit":"537f045bded0ad087c8a5191915e521e5130efa0"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fhttp-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fhttp-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fhttp-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggo%2Fhttp-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggo","download_url":"https://codeload.github.com/swaggo/http-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310515,"owners_count":22049469,"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":["golang","middleware","swagger2"],"created_at":"2024-09-24T20:28:39.001Z","updated_at":"2025-05-15T09:07:46.512Z","avatar_url":"https://github.com/swaggo.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# http-swagger\n\nDefault net/http wrapper to automatically generate RESTful API documentation with Swagger 2.0.\n\n[![Build Status](https://github.com/swaggo/http-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/http-swagger/master.svg)](https://codecov.io/gh/swaggo/http-swagger)\n[![Go Report Card](https://goreportcard.com/badge/github.com/swaggo/http-swagger)](https://goreportcard.com/report/github.com/swaggo/http-swagger)\n[![GoDoc](https://godoc.org/github.com/swaggo/http-swagger?status.svg)](https://godoc.org/github.com/swaggo/http-swagger)\n[![Release](https://img.shields.io/github/release/swaggo/http-swagger.svg?style=flat-square)](https://github.com/swaggo/http-swagger/releases)\n\n## Usage\nV2 require go 1.16 or higher due to the use of `embed` package.\n \n### Start using it\n1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).\n2. Download [Swag](https://github.com/swaggo/swag) for Go by using:\n```sh\ngo install github.com/swaggo/swag/cmd/swag@latest\n```\nTo build from source you need [Go](https://golang.org/dl/) (1.17 or newer).\n\nOr download a pre-compiled binary from the [release page](https://github.com/swaggo/swag/releases).\n\n3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).\n```sh\nswag init\n```\n4. Download [http-swagger](https://github.com/swaggo/http-swagger) by using:\n```sh\ngo get -u github.com/swaggo/http-swagger\n```\nAnd import following in your code:\n\n```go\nimport \"github.com/swaggo/http-swagger\" // http-swagger middleware\n```\n\n### Canonical example:\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/go-chi/chi\"\n\t\"github.com/swaggo/http-swagger/v2\"\n\t_ \"github.com/swaggo/http-swagger/example/go-chi/docs\" // docs is generated by Swag CLI, you have to import it.\n)\n\n// @title Swagger Example API\n// @version 1.0\n// @description This is a sample server Petstore server.\n// @termsOfService http://swagger.io/terms/\n\n// @contact.name API Support\n// @contact.url http://www.swagger.io/support\n// @contact.email support@swagger.io\n\n// @license.name Apache 2.0\n// @license.url http://www.apache.org/licenses/LICENSE-2.0.html\n\n// @host petstore.swagger.io\n// @BasePath /v2\nfunc main() {\n\tr := chi.NewRouter()\n\n\tr.Get(\"/swagger/*\", httpSwagger.Handler(\n\t\thttpSwagger.URL(\"http://localhost:1323/swagger/doc.json\"), //The url pointing to API definition\n\t))\n\n\thttp.ListenAndServe(\":1323\", r)\n}\n\n```\n\n5. Run it, and browser to http://localhost:1323/swagger/index.html, you can see Swagger 2.0 Api documents.\n\n![swagger_index.html](https://user-images.githubusercontent.com/8943871/36250587-40834072-1279-11e8-8bb7-02a2e2fdd7a7.png)\n\n### Optional configuration\n\nAs documented [here](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/), you can customize `SwaggerUI` with options and plugins. This package supports that customization with the `Plugins` and `UIConfig` options. These may be set to generate plugin lines and configuration parameters in the generated `SwaggerUI` JavaScript.\n\nIn addition, `BeforeScript` and `AfterScript` options may be used to generate JavaScript before and after `SwaggerUIBundle` creation, respectively. `BeforeScript` may be used to declare a plugin, for example, and `AfterScript` may be used to run a block of JavaScript on page load.\n\n#### A trivial example\n\nTo illustrate these options, take the following code:\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/go-chi/chi\"\n\t\"github.com/swaggo/http-swagger/v2\"\n\t_ \"github.com/swaggo/http-swagger/example/go-chi/docs\"\n)\n\n// @title Swagger Example API\n// @version 1.0\n// @description This is a sample server Petstore server.\n// @termsOfService http://swagger.io/terms/\n\n// @contact.name API Support\n// @contact.url http://www.swagger.io/support\n// @contact.email support@swagger.io\n\n// @license.name Apache 2.0\n// @license.url http://www.apache.org/licenses/LICENSE-2.0.html\n\n// @host petstore.swagger.io\n// @BasePath /v2\nfunc main() {\n\tr := chi.NewRouter()\n\n\tr.Get(\"/swagger/*\", httpSwagger.Handler(\n\t\thttpSwagger.URL(\"http://localhost:1323/swagger/doc.json\"),\n\t\thttpSwagger.BeforeScript(`const SomePlugin = (system) =\u003e ({\n    // Some plugin\n  });\n`),\n\t\thttpSwagger.AfterScript(`const someOtherCode = function(){\n    // Do something\n  };\n  someOtherCode();`),\n\t\thttpSwagger.Plugins([]string{\n\t\t\t\"SomePlugin\",\n\t\t\t\"AnotherPlugin\",\n\t\t}),\n\t\thttpSwagger.UIConfig(map[string]string{\n\t\t\t\"showExtensions\":        \"true\",\n\t\t\t\"onComplete\":            `() =\u003e { window.ui.setBasePath('v3'); }`,\n\t\t\t\"defaultModelRendering\": `\"model\"`,\n\t\t}),\n\t))\n\n\thttp.ListenAndServe(\":1323\", r)\n}\n\n```\n\nWhen you then open Swagger UI and inspect the source JavaScript, you would see the following:\n\n```javascript\nwindow.onload = function() {\n  const SomePlugin = (system) =\u003e ({\n    // Some plugin\n  });\n\n  const ui = SwaggerUIBundle({\n    url: \"swagger.json\",\n    deepLinking:  false ,\n    docExpansion: \"none\",\n    dom_id: \"swagger-ui-id\",\n    validatorUrl: null,\n    persistAuthorization: false,\n    presets: [\n      SwaggerUIBundle.presets.apis,\n      SwaggerUIStandalonePreset\n    ],\n    plugins: [\n      SwaggerUIBundle.plugins.DownloadUrl,\n      SomePlugin,\n      AnotherPlugin\n    ],\n    defaultModelRendering: \"model\",\n    onComplete: () =\u003e { window.ui.setBasePath('v3'); },\n    showExtensions: true,\n    layout: \"StandaloneLayout\"\n  })\n\n  window.ui = ui\n  const someOtherCode = function(){\n    // Do something\n  };\n  someOtherCode();\n}\n```\n\n#### A practical example\n\nTo illustrate a real use case, these options make it possible to dynamically set the API base path in the Swagger doc. The Swagger UI project has an [open issue on how to achieve this with a plugin](https://github.com/swagger-api/swagger-ui/issues/5981). That may be done as follows:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"net/url\"\n\n\t\"github.com/go-chi/chi\"\n\t\"github.com/swaggo/http-swagger/v2\"\n\t_ \"github.com/swaggo/http-swagger/example/go-chi/docs\"\n)\n\n// @title Swagger Example API\n// @version 1.0\n// @description This is a sample server Petstore server.\n// @termsOfService http://swagger.io/terms/\n\n// @contact.name API Support\n// @contact.url http://www.swagger.io/support\n// @contact.email support@swagger.io\n\n// @license.name Apache 2.0\n// @license.url http://www.apache.org/licenses/LICENSE-2.0.html\n\n// @host petstore.swagger.io\n// @BasePath /v2\nfunc main() {\n\tr := chi.NewRouter()\n\n\turi, err := url.Parse(\"http://localhost:1323/api/v3\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tr.Get(\"/swagger/*\", httpSwagger.Handler(\n\t\thttpSwagger.URL(\"http://localhost:1323/swagger/doc.json\"),\n\t\thttpSwagger.BeforeScript(`const UrlMutatorPlugin = (system) =\u003e ({\n  rootInjects: {\n    setScheme: (scheme) =\u003e {\n      const jsonSpec = system.getState().toJSON().spec.json;\n      const schemes = Array.isArray(scheme) ? scheme : [scheme];\n      const newJsonSpec = Object.assign({}, jsonSpec, { schemes });\n\n      return system.specActions.updateJsonSpec(newJsonSpec);\n    },\n    setHost: (host) =\u003e {\n      const jsonSpec = system.getState().toJSON().spec.json;\n      const newJsonSpec = Object.assign({}, jsonSpec, { host });\n\n      return system.specActions.updateJsonSpec(newJsonSpec);\n    },\n    setBasePath: (basePath) =\u003e {\n      const jsonSpec = system.getState().toJSON().spec.json;\n      const newJsonSpec = Object.assign({}, jsonSpec, { basePath });\n\n      return system.specActions.updateJsonSpec(newJsonSpec);\n    }\n  }\n});`),\n\t\thttpSwagger.Plugins([]string{\"UrlMutatorPlugin\"}),\n\t\thttpSwagger.UIConfig(map[string]string{\n\t\t\t\"onComplete\": fmt.Sprintf(`() =\u003e {\n    window.ui.setScheme('%s');\n    window.ui.setHost('%s');\n    window.ui.setBasePath('%s');\n  }`, uri.Scheme, uri.Host, uri.Path),\n\t\t}),\n\t))\n\n\thttp.ListenAndServe(\":1323\", r)\n}\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggo%2Fhttp-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggo%2Fhttp-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggo%2Fhttp-swagger/lists"}