{"id":37163026,"url":"https://github.com/ruiborda/go-swagger-generator","last_synced_at":"2026-01-14T19:23:45.925Z","repository":{"id":293588720,"uuid":"983907344","full_name":"ruiborda/go-swagger-generator","owner":"ruiborda","description":"Go Swagger Generator is a library that makes it easy to generate OpenAPI documentation directly from your Go code with a fluid and elegant API.","archived":false,"fork":false,"pushed_at":"2025-12-11T00:20:06.000Z","size":444,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"v2","last_synced_at":"2025-12-11T12:49:27.756Z","etag":null,"topics":["api","documentation","go","golang","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"https://go-swagger.pages.dev/","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/ruiborda.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-15T05:21:58.000Z","updated_at":"2025-12-11T00:20:11.000Z","dependencies_parsed_at":"2025-12-11T04:09:27.290Z","dependency_job_id":null,"html_url":"https://github.com/ruiborda/go-swagger-generator","commit_stats":null,"previous_names":["ruiborda/go-swagger-generator"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ruiborda/go-swagger-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruiborda%2Fgo-swagger-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruiborda%2Fgo-swagger-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruiborda%2Fgo-swagger-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruiborda%2Fgo-swagger-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruiborda","download_url":"https://codeload.github.com/ruiborda/go-swagger-generator/tar.gz/refs/heads/v2","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruiborda%2Fgo-swagger-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28432587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T18:57:19.464Z","status":"ssl_error","status_checked_at":"2026-01-14T18:52:48.501Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","documentation","go","golang","swagger","swagger-ui"],"created_at":"2026-01-14T19:23:45.414Z","updated_at":"2026-01-14T19:23:45.910Z","avatar_url":"https://github.com/ruiborda.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go Swagger Generator v2\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/ruiborda/go-swagger-generator.svg)](https://pkg.go.dev/github.com/ruiborda/go-swagger-generator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nGo Swagger Generator v2 is a library that facilitates the generation of **OpenAPI 3.0** documentation directly from your Go code with a fluent and elegant API.\n\n## Features\n\n- **Fluent and elegant API** - Chained syntax that makes OpenAPI 3.0 documentation easy to read and write.\n- **Simple integration with Gin** - Works with the popular Gin web framework without complications.\n- **No annotations required** - Does not require special comments in your code.\n- **Built-in Swagger UI** - Includes Swagger UI to explore your API interactively, displaying your OpenAPI 3.0 specification.\n- **Compatible with OpenAPI 3.0** - Generates documentation following the OpenAPI 3.0 specification.\n\n## Installation\n\n```bash\n# Install Go Swagger Generator v2\n go get -u github.com/ruiborda/go-swagger-generator/v2\n```\n\nIf you use Gin:\n\n```bash\n# Install Gin Framework\n go get github.com/gin-gonic/gin\n```\n\n## Quick Start (v2)\n\nHere's a simple example showing how to integrate Go Swagger Generator v2 with Gin to produce OpenAPI 3.0 documentation:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\n\t\"github.com/gin-gonic/gin\"\n\t\"github.com/ruiborda/go-swagger-generator/v2/src/middleware\"\n\t\"github.com/ruiborda/go-swagger-generator/v2/src/openapi\"\n\t\"github.com/ruiborda/go-swagger-generator/v2/src/openapi_spec/mime\"\n\t\"github.com/ruiborda/go-swagger-generator/v2/src/swagger\"\n)\n\n// UserDto represents the user DTO.\ntype UserDto struct {\n\tID   int    `json:\"id\" yaml:\"id\"`\n\tName string `json:\"name\" yaml:\"name\"`\n}\n\nfunc main() {\n\trouter := gin.Default()\n\n\t// Configure OpenAPI 3.0 documentation\n\tConfigureOpenAPI(router)\n\n\t// Define API route. The /v1 prefix should match the server URL in the OpenAPI config.\n\trouter.GET(\"/v1/users/:id\", GetUserByIdHandler)\n\n\tfmt.Println(\"Server running at http://localhost:8080\")\n\tfmt.Println(\"Swagger UI available at http://localhost:8080/\")\n\tfmt.Println(\"OpenAPI 3.0 JSON available at http://localhost:8080/openapi.json\")\n\t_ = router.Run(\":8080\")\n}\n\n// Handler to get user by ID.\nfunc GetUserByIdHandler(c *gin.Context) {\n\tidStr := c.Param(\"id\")\n\tc.JSON(http.StatusOK, UserDto{\n\t\tID:   1,\n\t\tName: \"John Doe (User \" + idStr + \")\",\n\t})\n}\n\n// Configure OpenAPI 3.0 documentation.\nfunc ConfigureOpenAPI(router *gin.Engine) {\n\trouter.Use(middleware.SwaggerGin(middleware.SwaggerConfig{\n\t\tEnabled:  true,\n\t\tJSONPath: \"/openapi.json\",\n\t\tUIPath:   \"/\",\n\t\tTitle:    \"My API with OpenAPI 3.0 (v2)\",\n\t}))\n\n\tdoc := swagger.Swagger()\n\n\tdoc.Info(func(info openapi.Info) {\n\t\tinfo.Title(\"Simple User API v2\").\n\t\t\tVersion(\"1.0.0\").\n\t\t\tDescription(\"A simple API to manage users, documented with Go Swagger Generator v2 and OpenAPI 3.0.\")\n\t})\n\n\tdoc.Server(\"http://localhost:8080/v1\", func(server openapi.Server) {\n\t\tserver.Description(\"Local development server (v1)\")\n\t})\n\n\t_, _ = doc.ComponentSchemaFromDTO(\u0026UserDto{})\n\n\tvar _ = doc.Path(\"/users/{id}\").\n\t\tGet(func(op openapi.Operation) {\n\t\t\top.Summary(\"Find user by ID\").\n\t\t\t\tTag(\"User Management\").\n\t\t\t\tOperationID(\"getUserByIdV2\").\n\t\t\t\tPathParameter(\"id\", func(p openapi.Parameter) {\n\t\t\t\t\tp.Description(\"ID of the user to retrieve\").\n\t\t\t\t\t\tRequired(true).\n\t\t\t\t\t\tSchema(func(s openapi.Schema) {\n\t\t\t\t\t\t\ts.Type(\"integer\").Format(\"int64\")\n\t\t\t\t\t\t})\n\t\t\t\t}).\n\t\t\t\tResponse(http.StatusOK, func(r openapi.Response) {\n\t\t\t\t\tr.Description(\"Successful operation - user details returned\").\n\t\t\t\t\t\tContent(mime.ApplicationJSON, func(mt openapi.MediaType) {\n\t\t\t\t\t\t\tmt.SchemaFromDTO(\u0026UserDto{})\n\t\t\t\t\t\t})\n\t\t\t\t}).\n\t\t\t\tResponse(http.StatusNotFound, func(r openapi.Response) {\n\t\t\t\t\tr.Description(\"User not found\")\n\t\t\t\t})\n\t\t}).\n\t\tDoc()\n}\n```\n\n## Usage Guide (v2 with OpenAPI 3.0)\n\n### 1. Configure OpenAPI in your Gin application\n\n```go\nfunc ConfigureOpenAPI(router *gin.Engine) {\n\trouter.Use(middleware.SwaggerGin(middleware.SwaggerConfig{\n\t\tEnabled:  true,\n\t\tJSONPath: \"/openapi.json\",\n\t\tUIPath:   \"/\",\n\t\tTitle:    \"My API v2\",\n\t}))\n\tdoc := swagger.Swagger()\n\tdoc.Info(func(info openapi.Info) {\n\t\tinfo.Title(\"My Awesome API v2\").\n\t\t\tVersion(\"2.0.0\").\n\t\t\tDescription(\"This is an API example using Go Swagger Generator v2 with OpenAPI 3.0.\")\n\t})\n\tdoc.Server(\"http://localhost:8080/api/v2\", func(server openapi.Server) {\n\t\tserver.Description(\"Development server\")\n\t})\n}\n```\n\n### 2. Define your models (DTOs)\n\nAdd `yaml` tags if you plan to support YAML representations, consistent with OpenAPI examples.\n\n```go\ntype UserDto struct {\n\tID   int    `json:\"id\" yaml:\"id\"`\n\tName string `json:\"name\" yaml:\"name\"`\n}\n\n// Register the DTO with OpenAPI components:\n// _, _ = swagger.Swagger().ComponentSchemaFromDTO(\u0026UserDto{})\n```\n\n### 3. Document your endpoints (OpenAPI 3.0 style)\n\n```go\nvar _ = swagger.Swagger().Path(\"/items/{itemId}\")\n\t.Get(func(op openapi.Operation) {\n\t\top.Summary(\"Get an item by its ID\").\n\t\t\tTag(\"Items\").\n\t\t\tOperationID(\"getItemByIdV2\").\n\t\t\tPathParameter(\"itemId\", func(p openapi.Parameter) {\n\t\t\t\tp.Description(\"ID of the item to fetch\").\n\t\t\t\t\tRequired(true).\n\t\t\t\t\tSchema(func(s openapi.Schema) {\n\t\t\t\t\t\ts.Type(\"integer\").Format(\"int64\")\n\t\t\t\t\t})\n\t\t\t}).\n\t\t\tResponse(http.StatusOK, func(r openapi.Response) {\n\t\t\t\tr.Description(\"Successful operation - item found\").\n\t\t\t\t\tContent(mime.ApplicationJSON, func(mt openapi.MediaType) {\n\t\t\t\t\t\tmt.Schema(openapi.S().Type(\"object\").Property(\"message\", openapi.S().Type(\"string\")))\n\t\t\t\t\t})\n\t\t\t}).\n\t\t\tResponse(http.StatusNotFound, func(r openapi.Response) {\n\t\t\t\tr.Description(\"Item not found\")\n\t\t\t})\n\t}).\n\tDoc()\n```\n\n### 4. Implement your handler functions\n\n```go\nfunc GetItemById(c *gin.Context) {\n\titemId := c.Param(\"itemId\")\n\tc.JSON(http.StatusOK, gin.H{\n\t\t\"message\": \"Item \" + itemId + \" found\",\n\t})\n}\n```\n\n## Documentation (v2)\n\nCheck the `/doc_page` directory for detailed documentation on all features of Go Swagger Generator v2:\n\n- [Introduction (v2)](/doc_page/docs/intro.md)\n- [Quick Start (v2)](/doc_page/docs/quick-start.md)\n- [Defining Models (v2)](/doc_page/docs/defining-models.md)\n- [Path Parameters (v2)](/doc_page/docs/path-parameters.md)\n- [Query Parameters (v2)](/doc_page/docs/query-parameters.md)\n- [Request Bodies (v2)](/doc_page/docs/request-bodies.md)\n- [Responses (v2)](/doc_page/docs/responses.md)\n- [Security Schemes (v2)](/doc_page/docs/security.md)\n- [Array Responses (v2)](/doc_page/docs/array-responses.md)\n- [Production Configuration (v2)](/doc_page/docs/production.md)\n- And more...\n\n## Examples (v2)\n\nCheck the `/examples` directory for complete examples updated for v2:\n\n- [Basic Example (v2)](/examples/basic/main.go)\n- [Pet Store (v2)](/examples/pet_store/main.go)\n- [Array Response Example (v2)](/examples/array_response/main.go)\n- [JWT Bearer Auth Example (v2)](/examples/jwt_bearer/main.go)\n\n## Testing your documented API\n\n1. Start your application.\n2. Open your browser at the configured UI path (default: `http://localhost:YOUR_PORT/`, for example, http://localhost:8080/).\n3. You should see the Swagger UI interface displaying your API documented with OpenAPI 3.0.\n4. The OpenAPI 3.0 JSON specification will be available at the configured `JSONPath` (for example, `/openapi.json`).\n5. Explore the endpoints, review the required parameters, and test the calls directly from the interface.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Feel free to open an issue or submit a pull request.\n\n1. Fork the repository.\n2. Create your feature branch (`git checkout -b feature/my-feature`).\n3. Commit your changes (`git commit -m 'Add a new feature'`).\n4. Push to the branch (`git push origin feature/my-feature`).\n5. Open a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruiborda%2Fgo-swagger-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruiborda%2Fgo-swagger-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruiborda%2Fgo-swagger-generator/lists"}