{"id":15046535,"url":"https://github.com/ecube-labs/koa-x-router","last_synced_at":"2025-10-30T11:21:12.251Z","repository":{"id":183445841,"uuid":"656542810","full_name":"Ecube-Labs/koa-x-router","owner":"Ecube-Labs","description":"`koa-x-router` is a library that extends the functionality of `@koa/router` by providing validation and automatic API documentation features. It simplifies the process of defining routes, validating request data, and generating API documentation.","archived":false,"fork":false,"pushed_at":"2024-12-18T08:51:49.000Z","size":819,"stargazers_count":5,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-01T07:31:41.183Z","etag":null,"topics":["adaptor-pattern","documentation-generator","koa","koa-router","koajs","openapi","router","swagger","zod"],"latest_commit_sha":null,"homepage":"https://stackblitz.com/edit/koa-x-router-demo?file=index.ts","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ecube-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-21T06:51:09.000Z","updated_at":"2024-12-18T08:50:38.000Z","dependencies_parsed_at":"2023-07-24T14:47:02.381Z","dependency_job_id":"935678c3-7f38-4b41-beed-fd79ea070263","html_url":"https://github.com/Ecube-Labs/koa-x-router","commit_stats":null,"previous_names":["ecube-labs/koa-x-router"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ecube-Labs%2Fkoa-x-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ecube-Labs%2Fkoa-x-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ecube-Labs%2Fkoa-x-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ecube-Labs%2Fkoa-x-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ecube-Labs","download_url":"https://codeload.github.com/Ecube-Labs/koa-x-router/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238536064,"owners_count":19488647,"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":["adaptor-pattern","documentation-generator","koa","koa-router","koajs","openapi","router","swagger","zod"],"created_at":"2024-09-24T20:53:13.016Z","updated_at":"2025-10-27T18:30:21.186Z","avatar_url":"https://github.com/Ecube-Labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koa-x-router\n\n\u003cspan class=\"badge-npmversion\"\u003e\u003ca href=\"https://npmjs.org/package/koa-x-router\" title=\"View this project on NPM\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/koa-x-router.svg\" alt=\"NPM version\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\u003cspan class=\"badge-npmdownloads\"\u003e\u003ca href=\"https://npmjs.org/package/koa-x-router\" title=\"View this project on NPM\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/koa-x-router.svg\" alt=\"NPM downloads\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\n`koa-x-router` is a library that extends the functionality of `@koa/router` by providing validation and automatic API documentation features. It simplifies the process of defining routes, validating request data, and generating API documentation.\n\n## Features\n\n- **Validation**: With `koa-x-router`, you can perform validation using various validation libraries. The library provides adapters such as `JoiAdaptor` and `ZodAdaptor` that allow you to define validation schemas using popular validation libraries like `Joi` or `Zod`. You can also implement your own custom adapter by implementing the `XRouterAdaptor` interface.\n\n- **Automatic API Documentation**: `koa-x-router` automatically generates API documentation based on your route definitions. It extracts information about route paths, request methods, request/response data structures, and validation rules. The generated documentation can be accessed through an endpoint, making it convenient for developers to understand and consume your API.\n\n## Installation\n\nYou can install koa-x-router with joi using npm:\n\n```shell\nnpm install koa @koa/router koa-x-router joi\n```\n\nor install with zod using npm:\n\n```shell\nnpm install koa @koa/router koa-x-router zod\n```\n\n### with TypeScript\n\n```shell\nnpm install @types/koa @types/koa__router -D\n```\n\n## Usage\n\n[Demo](https://stackblitz.com/edit/koa-x-router-demo?file=index.ts)\n\nTo use `koa-x-router`, import it and initialize it with an instance of `@koa/router`. Here's a basic example:\n\n```ts\nimport Koa from \"koa\";\nimport bodyParser from \"koa-bodyparser\";\nimport Joi from \"joi\"\nimport { Router, JoiAdaptor, ZodAdaptor } from \"koa-x-router\";\n\nconst app = new Koa();\nconst router = new Router({\n  adaptors: [JoiAdaptor], // \u003c== Important!\n  // adaptors: [ZodAdaptor], // If you want to use with Zod\n  // adaptors: [JoiAdaptor, ZodAdaptor], // or both\n});\nconst docRouter = new Router();\n\n// Define a route with validation\nrouter.add({\n  method: \"get\",\n  path: \"/users\",\n  validate: {\n    query: Joi.object({\n      name: Joi.string(),\n    }),\n    output: {\n      200: {\n        body: Joi.array().items(\n          Joi.object({\n            name: Joi.string().required(),\n            age: Joi.number().positive().required(),\n          })\n        ),\n      },\n    },\n  },\n  handler: async (ctx) =\u003e {\n    // code...\n  },\n});\n\ndocRouter.get(\"/\", (ctx) =\u003e {\n  ctx.body = `\u003c!DOCTYPE html\u003e\n  \u003chtml\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e\n    \u003cmeta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\"\u003e\n    \u003ctitle\u003eAPI Documentation\u003c/title\u003e\n    \u003clink href=\"https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700\" rel=\"stylesheet\"\u003e\n    \u003cstyle\u003ebody{margin: 0;padding: 0;}\u003c/style\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003credoc spec-url='/openapi.json' lazy-rendering\u003e\u003c/redoc\u003e\n    \u003cscript src=\"https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n  \u003c/html\u003e`;\n});\n\ndocRouter.get(\"/openapi.json\", (ctx) =\u003e {\n  ctx.body = router.generateOpenApiSpecJson({\n    info: {\n      title: \"koa-x-router Demo API Docs\",\n      version: \"1.0.0\",\n    },\n  });\n});\n\napp.use(docRouter.routes());\napp.use(bodyParser());\napp.use(router.routes());\n\napp.listen(3000, () =\u003e {\n  console.log(\"Server listening on port 3000\");\n});\n```\n\nYou can also implement your custom adapter by implementing the `XRouterAdaptor` interface.\nThis allows you to use your preferred validation library for route validation.\n\n## Contributing\n\nContributions are welcome!\nIf you have any suggestions, bug reports, or feature requests, please open an issue.\n\n## License\n\nThis project is licensed under the Apache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecube-labs%2Fkoa-x-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecube-labs%2Fkoa-x-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecube-labs%2Fkoa-x-router/lists"}