{"id":15272376,"url":"https://github.com/long2ice/swagin","last_synced_at":"2025-07-03T15:05:33.677Z","repository":{"id":42629679,"uuid":"394693368","full_name":"long2ice/swagin","owner":"long2ice","description":"Swagger + Gin = SwaGin, a web framework based on Gin and Swagger","archived":false,"fork":false,"pushed_at":"2023-06-20T09:33:44.000Z","size":493,"stargazers_count":72,"open_issues_count":4,"forks_count":18,"subscribers_count":3,"default_branch":"dev","last_synced_at":"2025-04-12T09:43:20.739Z","etag":null,"topics":["api","fastapi","gin","golang","openapi","redoc","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"https://swagin.long2ice.io/docs","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/long2ice.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":null,"security":"security/apikey.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-10T14:54:54.000Z","updated_at":"2024-12-25T12:30:23.000Z","dependencies_parsed_at":"2024-06-18T21:22:54.094Z","dependency_job_id":"61c8f0f9-dc98-4adf-9f55-56a9b04d2261","html_url":"https://github.com/long2ice/swagin","commit_stats":null,"previous_names":["long2ice/fastgo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/long2ice/swagin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fswagin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fswagin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fswagin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fswagin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/long2ice","download_url":"https://codeload.github.com/long2ice/swagin/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/long2ice%2Fswagin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263348202,"owners_count":23452870,"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","fastapi","gin","golang","openapi","redoc","swagger","swagger-ui"],"created_at":"2024-09-30T09:05:43.054Z","updated_at":"2025-07-03T15:05:33.617Z","avatar_url":"https://github.com/long2ice.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger + Gin = SwaGin\n\n[![deploy](https://github.com/long2ice/swagin/actions/workflows/deploy.yml/badge.svg)](https://github.com/long2ice/swagin/actions/workflows/deploy.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/long2ice/swagin.svg)](https://pkg.go.dev/github.com/long2ice/swagin)\n\n**If you use [Fiber](https://github.com/gofiber/fiber), you can try my another similar\nproject [Fibers](https://github.com/long2ice/fibers).**\n\n## Introduction\n\n`SwaGin` is a web framework based on `Gin` and `Swagger`, which wraps `Gin` and provides built-in swagger api docs and\nrequest model validation.\n\n## Why I build this project?\n\nPrevious I have used [FastAPI](https://github.com/tiangolo/fastapi), which gives me a great experience in api docs\ngeneration, because nobody like writing api docs.\n\nNow I use `Gin` but I can't found anything like that, I found [swag](https://github.com/swaggo/swag) but which write\ndocs with comment is so stupid. So there is `SwaGin`.\n\n## Installation\n\n```shell\ngo get -u github.com/long2ice/swagin\n```\n\n## Online Demo\n\nYou can see online demo at \u003chttps://swagin.long2ice.io/docs\u003e or \u003chttps://swagin.long2ice.io/redoc\u003e.\n\n![](https://raw.githubusercontent.com/long2ice/swagin/dev/images/docs.png)\n![](https://raw.githubusercontent.com/long2ice/swagin/dev/images/redoc.png)\n\nAnd you can reference all usage in [examples](https://github.com/long2ice/swagin/tree/dev/examples).\n\n## Usage\n\n### Build Swagger\n\nFirstly, build a swagger object with basic information.\n\n```go\npackage examples\n\nimport (\n  \"github.com/getkin/kin-openapi/openapi3\"\n  \"github.com/long2ice/swagin/swagger\"\n)\n\nfunc NewSwagger() *swagger.Swagger {\n  return swagger.New(\"SwaGin\", \"Swagger + Gin = SwaGin\", \"0.1.0\",\n    swagger.License(\u0026openapi3.License{\n      Name: \"Apache License 2.0\",\n      URL:  \"https://github.com/long2ice/swagin/blob/dev/LICENSE\",\n    }),\n    swagger.Contact(\u0026openapi3.Contact{\n      Name:  \"long2ice\",\n      URL:   \"https://github.com/long2ice\",\n      Email: \"long2ice@gmail.com\",\n    }),\n    swagger.TermsOfService(\"https://github.com/long2ice\"),\n  )\n}\n```\n\n### Write API\n\nThen write a router function.\n\n```go\npackage examples\n\ntype TestQuery struct {\n  Name string `query:\"name\" validate:\"required\" json:\"name\" description:\"name of model\" default:\"test\"`\n}\n\nfunc TestQuery(c *gin.Context, req TestQueryReq) error {\n  return c.JSON(req)\n}\n\n// TestQueryNoReq if there is no req body and query\nfunc TestQueryNoReq(c *gin.Context) {\n  c.JSON(http.StatusOK, \"{}\")\n}\n```\n\nNote that the attributes in `TestQuery`? `SwaGin` will validate request and inject it automatically, then you can use it\nin handler easily.\n\n### Write Router\n\nThen write router with some docs configuration and api.\n\n```go\npackage examples\n\nvar query = router.New(\n  TestQuery,\n  router.Summary(\"Test Query\"),\n  router.Description(\"Test Query Model\"),\n  router.Tags(\"Test\"),\n)\n\n// if there is no req body, you need use router.NewX\nvar query = router.NewX(\n  TestQueryNoReq,\n  router.Summary(\"Test Query\"),\n  router.Description(\"Test Query Model\"),\n  router.Tags(\"Test\"),\n)\n```\n\n### Security\n\nIf you want to project your api with a security policy, you can use security, also they will be shown in swagger docs.\n\nCurrent there is five kinds of security policies.\n\n- `Basic`\n- `Bearer`\n- `ApiKey`\n- `OpenID`\n- `OAuth2`\n\n```go\npackage main\n\nvar query = router.New(\n  TestQuery,\n  router.Summary(\"Test query\"),\n  router.Description(\"Test query model\"),\n  router.Security(\u0026security.Basic{}),\n)\n```\n\nThen you can get the authentication string by `context.MustGet(security.Credentials)` depending on your auth type.\n\n```go\npackage main\n\nfunc TestQuery(c *gin.Context) {\n  user := c.MustGet(security.Credentials).(*security.User)\n  fmt.Println(user)\n  c.JSON(http.StatusOK, t)\n}\n```\n\n### Mount Router\n\nThen you can mount router in your application or group.\n\n```go\npackage main\n\nfunc main() {\n  app := swagin.New(NewSwagger())\n  queryGroup := app.Group(\"/query\", swagin.Tags(\"Query\"))\n  queryGroup.GET(\"\", query)\n  queryGroup.GET(\"/:id\", queryPath)\n  queryGroup.DELETE(\"\", query)\n  app.GET(\"/noModel\", noModel)\n}\n\n```\n\n### Start APP\n\nFinally, start the application with routes defined.\n\n```go\npackage main\n\nimport (\n  \"github.com/gin-contrib/cors\"\n  \"github.com/long2ice/swagin\"\n)\n\nfunc main() {\n  app := swagin.New(NewSwagger())\n  app.Use(cors.New(cors.Config{\n    AllowOrigins:     []string{\"*\"},\n    AllowMethods:     []string{\"*\"},\n    AllowHeaders:     []string{\"*\"},\n    AllowCredentials: true,\n  }))\n\n  queryGroup := app.Group(\"/query\", swagin.Tags(\"Query\"))\n  queryGroup.GET(\"\", query)\n  queryGroup.GET(\"/:id\", queryPath)\n  queryGroup.DELETE(\"\", query)\n\n  formGroup := app.Group(\"/form\", swagin.Tags(\"Form\"))\n  formGroup.POST(\"/encoded\", formEncode)\n  formGroup.PUT(\"\", body)\n\n  app.GET(\"/noModel\", noModel)\n  app.POST(\"/body\", body)\n  if err := app.Run(); err != nil {\n    panic(err)\n  }\n}\n```\n\nThat's all! Now you can visit \u003chttp://127.0.0.1:8080/docs\u003e or \u003chttp://127.0.0.1:8080/redoc\u003e to see the api docs. Have\nfun!\n\n### Disable Docs\n\nIn some cases you may want to disable docs such as in production, just put `nil` to `swagin.New`.\n\n```go\napp = swagin.New(nil)\n```\n\n### SubAPP Mount\n\nIf you want to use sub application, you can mount another `SwaGin` instance to main application, and their swagger docs\nis also separate.\n\n```go\npackage main\n\nfunc main() {\n  app := swagin.New(NewSwagger())\n  subApp := swagin.New(NewSwagger())\n  subApp.GET(\"/noModel\", noModel)\n  app.Mount(\"/sub\", subApp)\n}\n\n```\n\n## Integration Tests\n\nFirst install Venom at \u003chttps://github.com/intercloud/venom/releases\u003e. Then you can run integration tests as follows:\n\n```\n$ cd examples\n$ go test\n```\n\nThis will start example application and run integration tests in directory *examples/test* against it.\n\nYou can also run integration tests on running example application with:\n\n```\n$ cd examples\n$ go build\n$ ./examples \u0026\n$ PID=$!\n$ venom run test/*.yml\n$ kill $PID\n```\n\n## ThanksTo\n\n- [kin-openapi](https://github.com/getkin/kin-openapi), OpenAPI 3.0 implementation for Go (parsing, converting,\n  validation, and more).\n- [Gin](https://github.com/gin-gonic/gin), an HTTP web framework written in Go (Golang).\n\n## License\n\nThis project is licensed under the\n[Apache-2.0](https://github.com/long2ice/swagin/blob/master/LICENSE)\nLicense.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flong2ice%2Fswagin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flong2ice%2Fswagin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flong2ice%2Fswagin/lists"}