{"id":13680221,"url":"https://github.com/mikkeloscar/gin-swagger","last_synced_at":"2025-04-05T11:09:18.079Z","repository":{"id":23800426,"uuid":"83900671","full_name":"mikkeloscar/gin-swagger","owner":"mikkeloscar","description":"DRY templates for go-swagger","archived":false,"fork":false,"pushed_at":"2025-03-24T11:08:53.000Z","size":7939,"stargazers_count":91,"open_issues_count":4,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T10:07:29.668Z","etag":null,"topics":["api-first","gin","gin-gonic","go-swagger","openapi","opentracing","swagger"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikkeloscar.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-03-04T14:50:26.000Z","updated_at":"2025-03-24T11:08:56.000Z","dependencies_parsed_at":"2023-11-20T11:27:30.857Z","dependency_job_id":"f54d59b3-20a3-4408-b4df-0f183993468a","html_url":"https://github.com/mikkeloscar/gin-swagger","commit_stats":{"total_commits":244,"total_committers":17,"mean_commits":"14.352941176470589","dds":0.4590163934426229,"last_synced_commit":"96bbc862a029176e9869c9298ec9aa7f260091a3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikkeloscar%2Fgin-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikkeloscar%2Fgin-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikkeloscar%2Fgin-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikkeloscar%2Fgin-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikkeloscar","download_url":"https://codeload.github.com/mikkeloscar/gin-swagger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"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":["api-first","gin","gin-gonic","go-swagger","openapi","opentracing","swagger"],"created_at":"2024-08-02T13:01:14.422Z","updated_at":"2025-04-05T11:09:18.060Z","avatar_url":"https://github.com/mikkeloscar.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# gin-swagger - DRY templates for go-swagger\n\ngin-swagger is a tool assisting in writing golang REST APIs based on a [API\nFirst Principle][api-first]. Given a swagger spec of your REST API,\n`gin-swagger` can generate all the boring boilerplate stuff for you, so you\nonly have to implement the core business logic of the API.\n\nIt is based on [go-swagger][go-swagger] which is used for the code generation.\n\n## Install\n\nYou can simply run `go get` to install gin-swagger.\n\n```\n$ go get github.com/mikkeloscar/gin-swagger\n$ gin-swagger --help\nusage: gin-swagger --application=APPLICATION [\u003cflags\u003e]\n\nFlags:\n      --help                     Show context-sensitive help (also try --help-long and --help-man).\n  -A, --application=APPLICATION  Name of the application (passed directly to swagger).\n  -f, --spec=\"./swagger.json\"    the spec file to use.\n```\n\n## How it works\n\ngin-swagger generates a [gin][gin] based REST API given a swagger spec.\n\nAssuming the following swagger spec:\n\n```yaml\nswagger: '2.0'\ninfo:\n  version: \"0.0.1\"\n  title: My API\nschemes:\n    - \"https\"\nbasePath: /\nproduces:\n  - application/json\nconsumes:\n  - application/json\npaths:\n  '/persons/{name}':\n    get:\n      summary: get Person\n      tags:\n        - Person\n      operationId: getPerson\n      responses:\n        200:\n          description: Person by name.\n          schema:\n            '$ref': '#/definitions/Person'\nparameters:\n  name:\n    name: name\n    in: path\n    type: string\n    required: true\n    pattern: \"^[a-z][a-z0-9]$\"\ndefinitions:\n  Person:\n    type: object\n    properties:\n      name:\n        type: string\n```\n\nYou can generate the REST API using the following command:\n\n```bash\n$ gin-swagger -A my-api -f swagger.yaml\n```\n\nThis will generate two folders `models/` and `restapi/`. `models/` contains\nmodel structs based on the *definitions* defined in your swagger file,\nincluding model validation, this is generated by [go-swagger][go-swagger].\n`restapi/` will contain everything generated by `gin-swagger` and can be\noverwritten when updating and regenerating your swagger spec. `restapi/api.go`\nwill contain a generated `Service` interface which is all you have to implement\nin order to add logic to your REST api.\n\nGiven the above swagger spec, the `Service` interface will look like this:\n\n```go\ntype Service interface {\n    Healthy() bool\n    GetPerson(ctx *gin.Context, params *persons.GetPersonParams) *api.Response\n}\n```\n\nThe `Healthy() bool` method should return true if the service is considered\nhealthy. The return value is used by the default health endpoint `/healthz`\nprovided by `gin-swagger`.\n\nThe `GetPerson()` method should implement the business logic of the\n`/persons/{name}` path of your REST API.\n\nA simple service implementation looks like this:\n\n```go\ntype mySvc struct {\n    health bool\n}\n\nfunc (m *mySvc) GetPerson(ctx *gin.Context, params *persons.GetPersonParams) *api.Response {\n    return \u0026api.Response{\n        Code: http.StatusOK,\n        Body: \u0026models.Person{Name: params.Name},\n    }\n}\n\nfunc (m *mySvc) Healthy() bool {\n    return m.health\n}\n```\n\nWith the service implemented the only thing left to do is plug it into\n`gin-swagger` and run it from your `main.go` (or wherever you like):\n\n```go\npackage main\n\nimport ...\n\nvar apiConfig restapi.Config\n\nfunc main() {\n    err := apiConfig.Parse()\n    if err != nil {\n        log.Fatal(err)\n    }\n    svc := \u0026mySvc{health: true}\n    api := restapi.NewServer(svc, \u0026apiConfig)\n    err = api.RunWithSigHandler()\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n`restapi.Config` is a default config object defined by `gin-swagger` it lets\nyou configure default options through commandline flags when starting the\nserver. For instance you can tell the server to serve HTTP only with the\n`--insecure-http` flag (default is to serve HTTPS).\n\nFor a full example see the [example folder](example).\n\n## Features\n* [ ] Validate + bind input to gin ctx.\n  * [x] bind body input.\n    * [ ] [Nice to have] custom input Models with required fields.\n  * [x] bind params input.\n  * [x] bind query params input.\n  * [ ] consume more than `application/json`\n* [ ] Security.\n  * [ ] basic\n  * [ ] apiKey\n  * [ ] OAuth2\n    * [x] `password` (Bearer token)\n    * [ ] `accessCode`\n    * [ ] `application`\n    * [ ] `implicit`\n  * [ ] Auth chain\n  * [x] Custom authorize on individual routes.\n* [x] Set custom middleware on each router Pre/post 'main' handler.\n  * Use case pre: *custom authorization pre handler*.\n  * Use case post: *audit report events post handler*.\n* [ ] Ginize generated code.\n* [ ] Set and get user info (uid, realm) from gin context.\n* [ ] Response helper functions\n* [ ] Default metrics (prometheus)\n* [x] OpenTracing support\n\n[api-first]: https://zalando.github.io/restful-api-guidelines/\n[gin]: https://github.com/gin-gonic/gin\n[go-swagger]: https://github.com/go-swagger/go-swagger\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikkeloscar%2Fgin-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikkeloscar%2Fgin-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikkeloscar%2Fgin-swagger/lists"}