Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ecube-labs/koa-x-router
`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.
https://github.com/ecube-labs/koa-x-router
adaptor-pattern documentation-generator koa koa-router koajs openapi router swagger zod
Last synced: about 1 month ago
JSON representation
`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.
- Host: GitHub
- URL: https://github.com/ecube-labs/koa-x-router
- Owner: Ecube-Labs
- Created: 2023-06-21T06:51:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-07T00:50:24.000Z (about 1 month ago)
- Last Synced: 2024-10-11T13:21:00.418Z (about 1 month ago)
- Topics: adaptor-pattern, documentation-generator, koa, koa-router, koajs, openapi, router, swagger, zod
- Language: TypeScript
- Homepage: https://stackblitz.com/edit/koa-x-router-demo?file=index.ts
- Size: 720 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# koa-x-router
`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.
## Features
- **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.
- **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.
## Installation
You can install koa-x-router with joi using npm:
```shell
npm install koa @koa/router koa-x-router joi
```
or install with zod using npm:
```shell
npm install koa @koa/router koa-x-router zod
```
### with TypeScript
```shell
npm install @types/koa @types/koa__router -D
```
## Usage
[Demo](https://stackblitz.com/edit/koa-x-router-demo?file=index.ts)
To use `koa-x-router`, import it and initialize it with an instance of `@koa/router`. Here's a basic example:
```ts
import Koa from "koa";
import bodyParser from "koa-bodyparser";
import Joi from "joi"
import { Router, JoiAdaptor, ZodAdaptor } from "koa-x-router";
const app = new Koa();
const router = new Router({
adaptors: [JoiAdaptor], // <== Important!
// adaptors: [ZodAdaptor], // If you want to use with Zod
// adaptors: [JoiAdaptor, ZodAdaptor], // or both
});
const docRouter = new Router();
// Define a route with validation
router.add({
method: "get",
path: "/users",
validate: {
query: Joi.object({
name: Joi.string(),
}),
output: {
200: {
body: Joi.array().items(
Joi.object({
name: Joi.string().required(),
age: Joi.number().positive().required(),
})
),
},
},
},
handler: async (ctx) => {
// code...
},
});
docRouter.get("/", (ctx) => {
ctx.body = `
API Documentation
body{margin: 0;padding: 0;}
`;
});
docRouter.get("/openapi.json", (ctx) => {
ctx.body = router.generateOpenApiSpecJson({
info: {
title: "koa-x-router Demo API Docs",
version: "1.0.0",
},
});
});
app.use(docRouter.routes());
app.use(bodyParser());
app.use(router.routes());
app.listen(3000, () => {
console.log("Server listening on port 3000");
});
```
You can also implement your custom adapter by implementing the `XRouterAdaptor` interface.
This allows you to use your preferred validation library for route validation.
## Contributing
Contributions are welcome!
If you have any suggestions, bug reports, or feature requests, please open an issue.
## License
This project is licensed under the Apache License 2.0.