{"id":16475030,"url":"https://github.com/davidebianchi/gswagger","last_synced_at":"2025-05-09T00:07:27.449Z","repository":{"id":37025006,"uuid":"303167454","full_name":"davidebianchi/gswagger","owner":"davidebianchi","description":"Generate an openapi spec dynamically based on the types used to handle request and response","archived":false,"fork":false,"pushed_at":"2024-11-08T18:52:36.000Z","size":338,"stargazers_count":35,"open_issues_count":4,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-09T00:07:18.231Z","etag":null,"topics":["echo","fiber","gorilla-mux","oas3","openapi","swagger"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/davidebianchi/gswagger","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/davidebianchi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":"support/echo/echo.go","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-11T16:46:42.000Z","updated_at":"2025-03-22T11:27:09.000Z","dependencies_parsed_at":"2023-10-03T12:52:21.452Z","dependency_job_id":"f6528042-c18b-42c6-8f7c-c80e278ac4f9","html_url":"https://github.com/davidebianchi/gswagger","commit_stats":{"total_commits":190,"total_committers":9,"mean_commits":21.11111111111111,"dds":"0.37368421052631584","last_synced_commit":"56651d1029b64ec8b5f4cfe2770e164dd9ee39bb"},"previous_names":["davidebianchi/gorilla-swagger"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidebianchi%2Fgswagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidebianchi%2Fgswagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidebianchi%2Fgswagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidebianchi%2Fgswagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidebianchi","download_url":"https://codeload.github.com/davidebianchi/gswagger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166520,"owners_count":21864482,"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":["echo","fiber","gorilla-mux","oas3","openapi","swagger"],"created_at":"2024-10-11T12:35:38.420Z","updated_at":"2025-05-09T00:07:27.417Z","avatar_url":"https://github.com/davidebianchi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![Build Status][github-actions-svg]][github-actions]\n[![Coverage Status](https://coveralls.io/repos/github/davidebianchi/gswagger/badge.svg?branch=main)](https://coveralls.io/github/davidebianchi/gswagger?branch=main)\n[![Go Report Card][go-report-card]][go-report-card-link]\n[![GoDoc][godoc-svg]][godoc-link]\n\n# gswagger\n\n\u003c/div\u003e\n\nGenerate an openapi spec dynamically based on the types used to handle request and response.\n\nIt works with any router, it is simple to add support to your router implementing the [apirouter](apirouter/router.go) interface.\n\nThe routers supported out of the box are:\n\n- [gorilla-mux](https://github.com/gorilla/mux)\n- [fiber](https://github.com/gofiber/fiber)\n- [echo](https://echo.labstack.com/)\n\nThis lib uses [kin-openapi] to automatically generate and serve a swagger file.\n\nTo convert struct to schemas, we use [jsonschema] library.  \nThe struct must contains the appropriate struct tags to be inserted in json schema to generate the schema dynamically.  \nIt is always possible to add a totally custom swagger schema using [kin-openapi].\n\n## Install\n\nTo use it, install with\n\n```sh\ngo get github.com/davidebianchi/gswagger\n```\n\n## Usage\n\nAn example usage of this lib with gorilla mux:\n\n```go\ncontext := context.Background()\nmuxRouter := mux.NewRouter()\n\nrouter, _ := swagger.NewRouter(gorilla.NewRouter(muxRouter), swagger.Options{\n  Context: context,\n  Openapi: \u0026openapi3.T{\n    Info: \u0026openapi3.Info{\n      Title:   \"my title\",\n      Version: \"1.0.0\",\n    },\n  },\n})\n\nokHandler := func(w http.ResponseWriter, req *http.Request) {\n  w.WriteHeader(http.StatusOK)\n  w.Write([]byte(\"OK\"))\n}\n\ntype User struct {\n  Name        string   `json:\"name\" jsonschema:\"title=The user name,required\" jsonschema_extras:\"example=Jane\"`\n  PhoneNumber int      `json:\"phone\" jsonschema:\"title=mobile number of user\"`\n  Groups      []string `json:\"groups,omitempty\" jsonschema:\"title=groups of the user,default=users\"`\n  Address     string   `json:\"address\" jsonschema:\"title=user address\"`\n}\ntype errorResponse struct {\n  Message string `json:\"message\"`\n}\n\nrouter.AddRoute(http.MethodPost, \"/users\", okHandler, swagger.Definitions{\n  RequestBody: \u0026swagger.ContentValue{\n    Content: swagger.Content{\n      \"application/json\": {Value: User{}},\n    },\n  },\n  Responses: map[int]swagger.ContentValue{\n    201: {\n      Content: swagger.Content{\n        \"text/html\": {Value: \"\"},\n      },\n    },\n    401: {\n      Content: swagger.Content{\n        \"application/json\": {Value: \u0026errorResponse{}},\n      },\n      Description: \"invalid request\",\n    },\n  },\n})\n\nrouter.AddRoute(http.MethodGet, \"/users\", okHandler, swagger.Definitions{\n  Responses: map[int]swagger.ContentValue{\n    200: {\n      Content: swagger.Content{\n        \"application/json\": {Value: \u0026[]User{}},\n      },\n    },\n  },\n})\n\ncarSchema := openapi3.NewObjectSchema().WithProperties(map[string]*openapi3.Schema{\n  \"foo\": openapi3.NewStringSchema(),\n  \"bar\": openapi3.NewIntegerSchema().WithMax(15).WithMin(5),\n})\nrequestBody := openapi3.NewRequestBody().WithJSONSchema(carSchema)\noperation := swagger.NewOperation()\noperation.AddRequestBody(requestBody)\n\nrouter.AddRawRoute(http.MethodPost, \"/cars\", okHandler, operation)\n\nrouter.GenerateAndExposeOpenapi()\n```\n\nThis configuration will output the schema shown [here](./support/gorilla/testdata/examples-users.json).\n\n## Auto generated path params schema\n\nThe path params, if not set in schema, are auto generated from the path.\nThe format of the path parameters depends on the router library you are using, as explained below.\n\n### Gorilla Mux\n\nGorilla Mux supports the path parameters as `{someParam}`, for example as in `/users/{userId}`.\n\nHere is the [example test](./support/gorilla/examples_test.go).\n\nThe generated oas schema will contains `userId`, `carId` and `driverId` as path params set to string.\nIf only one params is set, you must specify manually all the path params.\n\nThe generated OAS for this test case is visible [here](./support/gorilla/testdata/examples-users.json).\n\n### Fiber\nFiber supports the path parameters as `:someParam`, for example as in `/users/:userId`.\n\nHere is the [example test](./support/fiber/integration_test.go)\n\n## SubRouter\n\nIt is possible to create a new sub router from the swagger.Router.\nIt is possible to add a prefix to all the routes created under the specific router (instead of use the router specific methods, if given, or repeat the prefix for every route).\n\nIt could also be useful if you need a sub router to create a group of APIs which use the same middleware (for example,this could be achieved by the SubRouter features of gorilla mux, for example).\n\nTo see the SubRouter example, please see the integration test of one of the supported routers.\n\n### FAQ\n\n1. How to add format `binary`?\nFormats `date-time`, `email`, `hostname`, `ipv4`, `ipv6`, `uri` could be added with tag `jsonschema`. Others format could be added with tag `jsonschema_extra`. Not all the formats are supported (see discovered unsupported formats [here](#discovered-unsupported-schema-features)).\n\n1. How to add a swagger with `allOf`?\nYou can create manually a swagger with `allOf` using the `AddRawRoute` method.\n\n1. How to add a swagger with `anyOf`?\nYou can create manually a swagger with `anyOf` using the `AddRawRoute` method.\n\n1. How to add a swagger with `oneOf`?\nYou can create manually a swagger with `oneOf` using the `AddRawRoute` method, or use the [jsonschema] struct tag.\n\n#### Discovered unsupported schema features\n\n*Formats*:\n\n- `uuid` is unsupported by [kin-openapi]\n\n## Versioning\n\nWe use [SemVer][semver] for versioning. For the versions available,\nsee the [tags on this repository](https://github.com/davidebianchi/gswagger/tags).\n\n\u003c!-- Reference --\u003e\n[kin-openapi]: https://github.com/getkin/kin-openapi\n[jsonschema]: https://github.com/mia-platform/jsonschema\n[github-actions]: https://github.com/davidebianchi/gswagger/actions\n[github-actions-svg]: https://github.com/davidebianchi/gswagger/workflows/Test%20and%20build/badge.svg\n[godoc-svg]: https://godoc.org/github.com/davidebianchi/gswagger?status.svg\n[godoc-link]: https://godoc.org/github.com/davidebianchi/gswagger\n[go-report-card]: https://goreportcard.com/badge/github.com/davidebianchi/gswagger\n[go-report-card-link]: https://goreportcard.com/report/github.com/davidebianchi/gswagger\n[semver]: https://semver.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidebianchi%2Fgswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidebianchi%2Fgswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidebianchi%2Fgswagger/lists"}