Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/d-band/koa-mapper
A better and smart router middleware for koa.
https://github.com/d-band/koa-mapper
Last synced: 2 months ago
JSON representation
A better and smart router middleware for koa.
- Host: GitHub
- URL: https://github.com/d-band/koa-mapper
- Owner: d-band
- Created: 2019-02-25T02:14:28.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-07-31T22:21:30.000Z (almost 2 years ago)
- Last Synced: 2024-04-28T03:17:11.672Z (2 months ago)
- Language: JavaScript
- Size: 49.8 KB
- Stars: 39
- Watchers: 7
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Lists
- awesome-koa - koa-mapper - 更好的路由器支持参数验证和 OpenAPI 生成。   (仓库 / 中间件)
README
# koa-mapper
[](https://www.npmjs.com/package/koa-mapper)
[](https://www.npmjs.com/package/koa-mapper)
[](https://david-dm.org/d-band/koa-mapper)
[](https://travis-ci.org/d-band/koa-mapper)
[](https://coveralls.io/github/d-band/koa-mapper?branch=master) [](https://greenkeeper.io/)
> `koa-mapper` is a better and smart router middleware for koa. (Inspired by `koa-router`)
* Support almost all features of `koa-router`
* Support for parameters validation
* Support parameters in `path`, `header`, `query`, `cookie`
* Support body parser
* Support request body validation
* Support coerce data types of parameters and body
* Support OpenAPI generation
## Installation
```bash
npm install koa-mapper
```
## Example
```js
import Koa from 'koa';
import logger from 'koa-logger';
import Mapper from 'koa-mapper';
const app = new Koa();
app.use(logger());
const mapper = new Mapper();
mapper.get('/users/:id', {
params: {
id: { type: 'number' },
info: { type: 'User', in: 'query' }
}
}, (ctx) => {
ctx.body = ctx.params;
});
mapper.post('/users', {
body: {
users: { type: 'array' }
}
}, (ctx) => {
ctx.body = ctx.request.body;
});
mapper.define('User', {
id: { type: 'number', required: true },
name: { type: 'string', required: true }
});
app.use(mapper.routes());
app.use(mapper.allowedMethods());
app.listen(3000);
// open http://localhost:3000/users/123?info[id]=456&info[name]=hello
// open http://localhost:3000/openapi.json
```
## API Reference
### `new Mapper([options])`
**Options**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| prefix | `string` | `''` | the path prefix for a Mapper |
| openURL | `string` or `false` | `/openapi.json` | OpenAPI route, `false` to disable OpenAPI |
| bodyparser | `object` or `boolean` | `false` | `koa-body` options, `true|{}` to enable body parser |
| throwParamsError | `function` or `boolean` | `utils.validateError` | Throw error for params invalid |
| throwBodyError | `function` or `boolean` | `utils.validateError` | Throw error for body invalid |
| validator | `object` | `{}` | [`ajv options`](https://github.com/epoberezkin/ajv#options) |
| sensitive | `boolean` | `false` | `sensitive` option for [path-to-regexp](https://github.com/pillarjs/path-to-regexp) |
| strict | `boolean` | `false` | `strict` option for [path-to-regexp](https://github.com/pillarjs/path-to-regexp) |
### `mapper.get|put|post|del(path, [options], ...middlewares) => Mapper`
```js
type options = {
name: string, // route name, default null
prefix: string, // route prefix, default ''
bodyparser: object|boolean, // like Mapper options.bodyparser
throwParamsError: function, // like Mapper options.throwParamsError
throwBodyError: function, // like Mapper options.throwBodyError
params: Params, // OpenAPI parameters definition
body: Body, // OpenAPI requestBody schema definition
...others, // Fields of OpenAPI Operation Object
}
```
> More fields of [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operation-object)
```js
type Params = {
in: string, // parameter in: `path`, `query`, `header`, `cookie`
type: string, // parameter type
...others, // Fields of OpenAPI Parameter Object
}
```
> More fields of OpenAPI [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject)
`type` support:
* Basic type: `array`, `boolean`, `integer`, `null`, `number`, `object`, `string`, `date`, `time`, `datetime`, `regex`
* Array type: `array`, `array`
* Custom type: `Pet`, `array`
```js
type Body = string | {
[property]: Schema
}
```
body examples:
* `body: 'Pet'` => `body: { $ref: 'Pet' }`
* `body: { id: { type: 'number' } }` => `body: { type: 'object', properties: { id: { type: 'number' } }}`
### `mapper.schema(name, properties, options) => Mapper` alias `mapper.define()`
```js
mapper.schema('Tag', {
id: { type: 'integer', format: 'int64' },
name: { type: 'string' }
});
mapper.schema('Category', {
id: { type: 'integer', format: 'int64' },
name: { type: 'string' }
});
mapper.schema('Pet', {
id: { type: 'integer', format: 'int64' },
category: { type: 'Category' },
name: { type: 'string' },
photoUrls: { type: 'array' },
tags: { type: 'array' },
status: { type: 'string', enum: ['available', 'pending', 'sold'] }
}, {
required: ['name', 'photoUrls']
});
```
Support type extends:
```js
mapper.schema('Model', {
id: { type: 'number' },
createdAt: { type: 'datetime' },
updatedAt: { type: 'datetime' }
});
mapper.schema('User: Model', {
name: { type: 'string' }
});
```
### BodyParser
```js
mapper.post('/users', {
body: 'User'
}, (ctx) => {
const { id, name } = ctx.request.body;
});
```
Multipart and file upload:
```js
mapper.post('/uploadImage', {
bodyparser: { multipart: true },
body: {
user: { type: 'number' },
image: { type: 'file' }
}
}, (ctx) => {
const { user, image } = ctx.request.body;
});
```
## License
MIT