{"id":18586385,"url":"https://github.com/cardinalby/hureg","last_synced_at":"2026-03-27T04:41:42.414Z","repository":{"id":246075901,"uuid":"815667006","full_name":"cardinalby/hureg","owner":"cardinalby","description":"Huma registration extensions","archived":false,"fork":false,"pushed_at":"2024-11-24T12:22:09.000Z","size":237,"stargazers_count":26,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-30T20:05:19.101Z","etag":null,"topics":["go","groups","huma","middleware","openapi","router"],"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/cardinalby.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":"2024-06-15T19:17:53.000Z","updated_at":"2025-02-24T10:34:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"22a04f19-4fd5-4c64-9338-c4e08c7675a6","html_url":"https://github.com/cardinalby/hureg","commit_stats":null,"previous_names":["cardinalby/hureg"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardinalby%2Fhureg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardinalby%2Fhureg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardinalby%2Fhureg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardinalby%2Fhureg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cardinalby","download_url":"https://codeload.github.com/cardinalby/hureg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251774894,"owners_count":21641731,"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","groups","huma","middleware","openapi","router"],"created_at":"2024-11-07T00:38:05.806Z","updated_at":"2026-03-27T04:41:42.355Z","avatar_url":"https://github.com/cardinalby.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Reference](https://pkg.go.dev/badge/github.com/cardinalby/hureg.svg)](https://pkg.go.dev/github.com/cardinalby/hureg)\n[![list](https://github.com/cardinalby/hureg/actions/workflows/list.yml/badge.svg)](https://github.com/cardinalby/hureg/actions/workflows/list.yml)\n[![list](https://github.com/cardinalby/hureg/actions/workflows/list.yml/badge.svg)](https://github.com/cardinalby/hureg/actions/workflows/list.yml)\n\n![hureg logo](./docs/hureg.png)\n\n[HUMA](https://github.com/danielgtaylor/huma) is a great Go framework that enables you to \nexpose generated OpenAPI spec in the best way possible. Unfortunately, it lacks some features from other routers.\n\nThis library wraps [HUMA framework](https://github.com/danielgtaylor/huma) endpoints \nregistration pipeline to provide the missing features:\n\n### ❤️ Create registration **groups**\n\nSimilar to other routers you can create a derived `api` (i.e. group) that has pre-defined:\n- [**Base path**](./docs/base_path.md) (same as `Group`, `Route` methods in other routers) \n- [**Multiple**](./docs/base_path.md) alternative **base paths**\n- [**Middlewares**](./pkg/huma/op_handler/middlewares.go)\n  - including a [trick](./docs/huma_api_per_group.md) to use router-specific middlewares for a group \n- [**Transformers**](./docs/transformers.md)\n- [**Tags**](./pkg/huma/op_handler/add_tags.go) and [other](./pkg/huma/op_handler) Huma Operation properties \n  that will be applied to all endpoints in a group.\n- [**Control**](./docs/reg_middlewares.md) the registration pipeline preventing operation from \n  registration or registering it multiple times with different properties\n\n### ❤️ Control over OpenAPI endpoints\n\nNow you have [manual control](./docs/openapi_endpoints.md) over exposing the spec, docs and schemas:\n- Expose only needed spec versions\n- Add own middlewares (e.g. authentication to protect the spec on public APIs)\n- Have separate scoped OpenAPI specs for different parts of your API\n\n### ❤️ Access more metadata in Operation Handlers\n\nThe library [provides](./docs/metadata.md) additional information via `Metadata` field to your \nown _Operation Handlers_:\n- Input/Output types of a handler\n- OpenAPI object from `huma.API` instance\n- Whether an operation was defined explicitly or implicitly via convenience methods\n- etc.\n\n## Installation\n\n```bash\ngo get github.com/cardinalby/hureg\n```\n\n## Documentation\n\n### Key concepts\n\n- [Basic usage](./docs/basic_usage.md)\n- [Registration Middlewares](./docs/reg_middlewares.md)\n\n### Common use-cases\n\n- [Create a group with base path](./docs/base_path.md)\n- [Operation Handlers](./docs/op_handlers.md)\n\n### Additional features\n\n- [Operation metadata](./docs/metadata.md)\n- [Per-group Transformers](./docs/transformers.md)\n- [OpenAPI endpoints](./docs/openapi_endpoints.md) and multiple scoped specs\n\n## Examples\n\n### 🔻 Initialization\n\n```go\nimport \"github.com/cardinalby/hureg\"\n\nhttpServeMux := http.NewServeMux()              // with go 1.22\ncfg := huma.DefaultConfig(\"My API\", \"1.0.0\")    // default HUMA initialization\nhumaApi := humago.New(httpServeMux, cfg)        // --\n\napi := hureg.NewAPIGen(humaApi)    // The new line\n```\n\n### 🔻 \"Base path + tags + middlewares\" group\n\n```go\nv1gr := api.            // all operations registered with v1gr will have:\n\tAddBasePath(\"/v1\").                            // - \"/v1\" base path\n\tAddOpHandler(op_handler.AddTags(\"some_tag\")).  // - \"some_tag\" tag\n\tAddMiddlewares(m1, m2)                         // - m1, m2 middlewares\n\t\nhureg.Get(v1gr, \"/cat\", ...) // \"/v1/cat\" with \"some_tag\" tag and m1, m2 middlewares\nhureg.Get(v1gr, \"/dog\", ...) // \"/v1/dog\" with \"some_tag\" tag and m1, m2 middlewares\n```\n\n### 🔻 Multiple base paths\n\nSometimes we need to register the same endpoint with multiple base paths (e.g. `/v1` and `/v2`).\n\n```go\nmultiPathGr := api.AddMultiBasePaths(nil, \"/v1\", \"/v2\")\n\nhureg.Get(multiPathGr, \"/sparrow\", ...) // \"/v1/sparrow\"\n                                        // \"/v2/sparrow\"\n```\n\n### 🔻 Transformers per group\n\n```go\ntrGr := api.AddTransformers(...) // transformers will be applied only to the operations \n                                 // registered in this group\n\nhureg.Get(trGr, \"/crocodile\", ...)\n```\n\n### 🔻 Complete server setup\n\nCheck out [integration_test.go](./integration_test.go) for a complete example of how to use the library:\n- create `huma.API` from `http.ServeMux` router\n- create `APIGen` instance on top of `huma.API`\n- register operations with `APIGen` instance\n  - use base paths, tags and _Transformers_ to the groups\n  - register OpenAPI endpoints manually with Basic Auth middleware\n\nUncommenting one line you can run the server and play with it in live mode.\n\n## Go version\n\nEven though Huma declares Go 1.20 as the minimal supported version, it actually requires Go 1.22 for correct work\ndue to \"slices\" package usage. So `hureg` requires Go 1.22 explicitly.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardinalby%2Fhureg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardinalby%2Fhureg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardinalby%2Fhureg/lists"}