{"id":17968181,"url":"https://github.com/a-h/rest","last_synced_at":"2025-07-20T08:37:24.810Z","repository":{"id":65833533,"uuid":"599199253","full_name":"a-h/rest","owner":"a-h","description":"Generate OpenAPI 3.0 specifications from Go code.","archived":false,"fork":false,"pushed_at":"2024-08-15T14:00:32.000Z","size":2368,"stargazers_count":61,"open_issues_count":12,"forks_count":24,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-05T01:20:03.086Z","etag":null,"topics":["go","hacktoberfest","openapi","openapi3"],"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/a-h.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":"2023-02-08T16:53:48.000Z","updated_at":"2025-01-25T19:10:26.000Z","dependencies_parsed_at":"2024-04-16T11:43:13.740Z","dependency_job_id":"47020e5e-2625-4ff9-8bb5-45b854b4470e","html_url":"https://github.com/a-h/rest","commit_stats":{"total_commits":64,"total_committers":9,"mean_commits":7.111111111111111,"dds":0.25,"last_synced_commit":"6729b3328f851d4531b2dfc1ab6ffb30d4c8dbe7"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-h%2Frest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-h%2Frest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-h%2Frest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-h%2Frest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a-h","download_url":"https://codeload.github.com/a-h/rest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238504981,"owners_count":19483478,"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":["go","hacktoberfest","openapi","openapi3"],"created_at":"2024-10-29T14:20:28.016Z","updated_at":"2025-02-12T16:14:08.047Z","avatar_url":"https://github.com/a-h.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# REST\n\nDocument a REST API with an OpenAPI 3.0 specification.\n\n* Code, not configuration.\n* No magic comments, tags, or decorators.\n* Use with or without a Go web framework.\n* Populates schema automatically using reflection.\n\n## Why would I want to use this?\n\n* Add OpenAPI documentation to an API.\n  * Create a `swagger.json` or `swagger.yaml` file.\n* Serve the Swagger UI to customers.\n\n## Examples\n\nSee the [./examples](./examples) directory for complete examples.\n\n### Create an OpenAPI 3.0 (swagger) file\n\n```go\n// Configure the models.\napi := rest.NewAPI(\"messages\")\napi.StripPkgPaths = []string{\"github.com/a-h/rest/example\", \"github.com/a-h/respond\"}\n\napi.RegisterModel(rest.ModelOf[respond.Error](), rest.WithDescription(\"Standard JSON error\"), func(s *openapi3.Schema) {\n  status := s.Properties[\"statusCode\"]\n  status.Value.WithMin(100).WithMax(600)\n})\n\napi.Get(\"/topic/{id}\").\n  HasPathParameter(\"id\", rest.PathParam{\n    Description: \"id of the topic\",\n    Regexp:      `\\d+`,\n  }).\n  HasResponseModel(http.StatusOK, rest.ModelOf[models.Topic]()).\n  HasResponseModel(http.StatusInternalServerError, rest.ModelOf[respond.Error]())\n\n// Create the specification.\nspec, err := api.Spec()\nif err != nil {\n  log.Fatalf(\"failed to create spec: %v\", err)\n}\n\n// Write to stdout.\nenc := json.NewEncoder(os.Stdout)\nenc.SetIndent(\"\", \" \")\nenc.Encode(spec)\n```\n\n### Serve API documentation alongside your API\n\n```go\n// Create routes.\nrouter := http.NewServeMux()\nrouter.Handle(\"/topics\", \u0026get.Handler{})\nrouter.Handle(\"/topic\", \u0026post.Handler{})\n\napi := rest.NewAPI(\"messages\")\napi.StripPkgPaths = []string{\"github.com/a-h/rest/example\", \"github.com/a-h/respond\"}\n\n// Register the error type with customisations.\napi.RegisterModel(rest.ModelOf[respond.Error](), rest.WithDescription(\"Standard JSON error\"), func(s *openapi3.Schema) {\n  status := s.Properties[\"statusCode\"]\n  status.Value.WithMin(100).WithMax(600)\n})\n\napi.Get(\"/topics\").\n  HasResponseModel(http.StatusOK, rest.ModelOf[get.TopicsGetResponse]()).\n  HasResponseModel(http.StatusInternalServerError, rest.ModelOf[respond.Error]())\n\napi.Post(\"/topic\").\n  HasRequestModel(rest.ModelOf[post.TopicPostRequest]()).\n  HasResponseModel(http.StatusOK, rest.ModelOf[post.TopicPostResponse]()).\n  HasResponseModel(http.StatusInternalServerError, rest.ModelOf[respond.Error]())\n\n// Create the spec.\nspec, err := api.Spec()\nif err != nil {\n  log.Fatalf(\"failed to create spec: %v\", err)\n}\n\n// Apply any global customisation.\nspec.Info.Version = \"v1.0.0.\"\nspec.Info.Description = \"Messages API\"\n\n// Attach the Swagger UI handler to your router.\nui, err := swaggerui.New(spec)\nif err != nil {\n  log.Fatalf(\"failed to create swagger UI handler: %v\", err)\n}\nrouter.Handle(\"/swagger-ui\", ui)\nrouter.Handle(\"/swagger-ui/\", ui)\n\n// And start listening.\nfmt.Println(\"Listening on :8080...\")\nfmt.Println(\"Visit http://localhost:8080/swagger-ui to see API definitions\")\nfmt.Println(\"Listening on :8080...\")\nhttp.ListenAndServe(\":8080\", router)\n```\n\n## Tasks\n\n### test\n\n```\ngo test ./...\n```\n\n### run-example\n\nDir: ./examples/stdlib\n\n```\ngo run main.go\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-h%2Frest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa-h%2Frest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-h%2Frest/lists"}