{"id":15091501,"url":"https://github.com/go-andiamo/chioas","last_synced_at":"2025-09-09T13:39:50.862Z","repository":{"id":182984322,"uuid":"661307874","full_name":"go-andiamo/chioas","owner":"go-andiamo","description":"Go package for defining Chi apis (with OpenAPI generated specs)","archived":false,"fork":false,"pushed_at":"2025-01-24T18:18:09.000Z","size":1758,"stargazers_count":29,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T01:41:29.586Z","etag":null,"topics":["api","chi","go","golang","oas","openapi","swagger","swagger-ui"],"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/go-andiamo.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":"security.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-02T12:49:48.000Z","updated_at":"2025-03-24T02:02:48.000Z","dependencies_parsed_at":"2023-11-20T17:28:30.559Z","dependency_job_id":"e66507eb-8210-4205-8bb9-03818582bb92","html_url":"https://github.com/go-andiamo/chioas","commit_stats":{"total_commits":57,"total_committers":2,"mean_commits":28.5,"dds":0.01754385964912286,"last_synced_commit":"8dab78e6f43b781c21717670bba2184105f1687b"},"previous_names":["go-andiamo/chioas"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-andiamo%2Fchioas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-andiamo%2Fchioas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-andiamo%2Fchioas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-andiamo%2Fchioas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-andiamo","download_url":"https://codeload.github.com/go-andiamo/chioas/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525776,"owners_count":21118750,"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","chi","go","golang","oas","openapi","swagger","swagger-ui"],"created_at":"2024-09-25T10:41:25.816Z","updated_at":"2025-09-09T13:39:50.844Z","avatar_url":"https://github.com/go-andiamo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CHIOAS\n[![GoDoc](https://godoc.org/github.com/go-andiamo/chioas?status.svg)](https://pkg.go.dev/github.com/go-andiamo/chioas)\n[![Latest Version](https://img.shields.io/github/v/tag/go-andiamo/chioas.svg?sort=semver\u0026style=flat\u0026label=version\u0026color=blue)](https://github.com/go-andiamo/chioas/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/go-andiamo/chioas)](https://goreportcard.com/report/github.com/go-andiamo/chioas)\n\n*Chioas* is an add-on for the popular [Chi router](https://github.com/go-chi/chi)\n\n\u003e pronounce *Chioas* however you like...\n\u003e \n\u003e  but I can't help feeling that it looks a little like \"chaos\" - the chaos of undocumented APIs that it tries to solve!\n\n### What it does\n\n*Chioas* does three things:\n* Defines your API as a single (or modular) struct and then builds the Chi routes accordingly\n* Produces an OpenApi spec (OAS) of that definition\n* Optionally serves an interactive API docs web-page (as part of your service)\n\n### Advantages\nWith your actual API and OpenAPI spec (OAS) being specified in _**one**_ place there's no chance of them becoming out of sync! (eliminating having to manually update spec yaml/json to match API or vice versa)\n\nYou can even keep your request/response OAS schemas in sync with your request/response structs!\u003cbr\u003e\nSee [petstore example](https://github.com/go-andiamo/chioas/tree/main/_examples/petstore)\n\n### Already have an OAS spec?\nNo problem, use `chioas.FromJson()` or `chioas.FromYaml()` to read the spec definition.\nAll you'll need to do is add `x-handler` tags to each method in the spec.\n\nSee [From example](https://github.com/go-andiamo/chioas/tree/main/_examples/from)\n\nYou can also unmarshal OAS YAML/JSON directly into a *Chioas* `Definition` (but this won't bind handlers)\n\n### Choice of UI styles\n*Chioas* supports three different styles of API docs UI:\n1. Rapidoc (see [rapidoc](https://github.com/rapi-doc/RapiDoc))\n2. Swagger (see [swagger-ui](https://github.com/swagger-api/swagger-ui))\n3. Redoc (see [Redocly.redoc](https://github.com/Redocly/redoc) and [Redoc-try](https://github.com/wll8/redoc-try))\n\nSet the desired style using `DocOptions.UIStyle` (the default is `Redoc`).\nNotes:\n* statics for `Swagger` are all served directly from *Chioas*\n* statics for `Rapidoc` are all served directly from *Chioas*\n* statics for `Redoc` are served from CDNs\n\n*Chioas* also supports serving multiple styles of UI on different docs paths (see `DocOptions.AlternateUIDocs` and [example](https://github.com/go-andiamo/chioas/tree/main/_examples/multi_ui))\n\n### Added Bonus Features\nChioas comes with many bonus features that help in building complete APIs and specs...\n* Highly extensible - e.g. if there are parts of the OAS spec that are not directly supported by Chioas, then they can be added using the `Additional` field on each part\n* Optionally check that OAS refs (`$ref`) are valid _(see `DocOptions.CheckRefs`)_\n* Optional typed handlers - see [typed README](https://github.com/go-andiamo/chioas/blob/main/typed/README.md)\n* Optional automatically added `HEAD` methods for `GET` methods _(see `Definition.AutoHeadMethods`)_\n* Optional automatically added `OPTIONS` methods - with `Allow` header populated with actual allowed methods _(see `Definition.AutoOptionsMethods` and `Path.AutoOptionsMethod`)_\n* Optional automatically added Chi `MethodNotAllowed` handler to each path  - with `Allow` header populated with actual allowed methods _(see `Definition.AutoMethodNotAllowed`)_\n* Ref checking (useful for checking existing oas yaml/json)\n\n## Installation\nTo install chioas, use go get:\n\n    go get github.com/go-andiamo/chioas\n\nTo update chioas to the latest version, run:\n\n    go get -u github.com/go-andiamo/chioas\n\n## Basic Example\n```go\npackage main\n\nimport (\n    \"github.com/go-andiamo/chioas\"\n    \"github.com/go-chi/chi/v5\"\n    \"net/http\"\n)\n\nfunc main() {\n    router := chi.NewRouter()\n    if err := myApi.SetupRoutes(router, myApi); err != nil {\n        panic(err)\n    }\n    _ = http.ListenAndServe(\":8080\", router)\n}\n\nvar myApi = chioas.Definition{\n    AutoHeadMethods: true,\n    DocOptions: chioas.DocOptions{\n        ServeDocs:       true,\n        HideHeadMethods: true,\n    },\n    Paths: chioas.Paths{\n        \"/foos\": {\n            Methods: chioas.Methods{\n                http.MethodGet: {\n                    Handler: getFoos,\n                    Responses: chioas.Responses{\n                        http.StatusOK: {\n                            Description: \"List of foos\",\n                            IsArray:     true,\n                            SchemaRef:   \"foo\",\n                        },\n                    },\n                },\n                http.MethodPost: {\n                    Handler: postFoos,\n                    Request: \u0026chioas.Request{\n                        Description: \"Foo to create\",\n                        SchemaRef:   \"foo\",\n                    },\n                    Responses: chioas.Responses{\n                        http.StatusCreated: {\n                            Description: \"New foo\",\n                            SchemaRef:   \"foo\",\n                        },\n                    },\n                },\n                http.MethodHead: {\n                    Handler: getFoos,\n                },\n            },\n            Paths: chioas.Paths{\n                \"/{fooId}\": {\n                    Methods: chioas.Methods{\n                        http.MethodGet: {\n                            Handler: getFoo,\n                            Responses: chioas.Responses{\n                                http.StatusOK: {\n                                    Description: \"The foo\",\n                                    SchemaRef:   \"foo\",\n                                },\n                            },\n                        },\n                        http.MethodDelete: {\n                            Handler: deleteFoo,\n                        },\n                    },\n                },\n            },\n        },\n    },\n    Components: \u0026chioas.Components{\n        Schemas: chioas.Schemas{\n            {\n                Name:               \"foo\",\n                RequiredProperties: []string{\"name\", \"address\"},\n                Properties:         chioas.Properties{\n                    {\n                        Name: \"name\",\n                        Type: \"string\",\n                    },\n                    {\n                        Name: \"address\",\n                        Type: \"string\",\n                    },\n                },\n            },\n        },\n    },\n}\n\nfunc getFoos(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc postFoos(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc getFoo(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc deleteFoo(writer http.ResponseWriter, request *http.Request) {\n}\n```\nRun and then check out http://localhost:8080/docs !\n\nOr simply generate the OpenAPI spec...\n```go\npackage main\n\nimport (\n    \"net/http\"\n\n    \"github.com/go-andiamo/chioas\"\n)\n\nfunc main() {\n    data, _ := myApi.AsYaml()\n    println(string(data))\n}\n\nvar myApi = chioas.Definition{\n    AutoHeadMethods: true,\n    DocOptions: chioas.DocOptions{\n        ServeDocs:       true,\n        HideHeadMethods: true,\n    },\n    Paths: chioas.Paths{\n        \"/foos\": {\n            Methods: chioas.Methods{\n                http.MethodGet: {\n                    Handler: getFoos,\n                    Responses: chioas.Responses{\n                        http.StatusOK: {\n                            Description: \"List of foos\",\n                            IsArray:     true,\n                            SchemaRef:   \"foo\",\n                        },\n                    },\n                },\n                http.MethodPost: {\n                    Handler: postFoos,\n                    Request: \u0026chioas.Request{\n                        Description: \"Foo to create\",\n                        SchemaRef:   \"foo\",\n                    },\n                    Responses: chioas.Responses{\n                        http.StatusCreated: {\n                            Description: \"New foo\",\n                            SchemaRef:   \"foo\",\n                        },\n                    },\n                },\n                http.MethodHead: {\n                    Handler: getFoos,\n                },\n            },\n            Paths: chioas.Paths{\n                \"/{fooId}\": {\n                    Methods: chioas.Methods{\n                        http.MethodGet: {\n                            Handler: getFoo,\n                            Responses: chioas.Responses{\n                                http.StatusOK: {\n                                    Description: \"The foo\",\n                                    SchemaRef:   \"foo\",\n                                },\n                            },\n                        },\n                        http.MethodDelete: {\n                            Handler: deleteFoo,\n                        },\n                    },\n                },\n            },\n        },\n    },\n    Components: \u0026chioas.Components{\n        Schemas: chioas.Schemas{\n            {\n                Name:               \"foo\",\n                RequiredProperties: []string{\"name\", \"address\"},\n                Properties: chioas.Properties{\n                    {\n                        Name: \"name\",\n                        Type: \"string\",\n                    },\n                    {\n                        Name: \"address\",\n                        Type: \"string\",\n                    },\n                },\n            },\n        },\n    },\n}\n\nfunc getFoos(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc postFoos(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc getFoo(writer http.ResponseWriter, request *http.Request) {\n}\n\nfunc deleteFoo(writer http.ResponseWriter, request *http.Request) {\n}\n```\n[try on go-playground](https://go.dev/play/p/0zaWsmsw2FD)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-andiamo%2Fchioas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-andiamo%2Fchioas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-andiamo%2Fchioas/lists"}