Skip to content
This repository has been archived by the owner on Aug 28, 2023. It is now read-only.

Commit

Permalink
docs: update documents to 2.0
Browse files Browse the repository at this point in the history
split documents and update to 2.0
  • Loading branch information
amazing-gao committed Jan 28, 2018
1 parent d26580f commit f91fd9e
Show file tree
Hide file tree
Showing 10 changed files with 1,173 additions and 1,322 deletions.
940 changes: 280 additions & 660 deletions README.md

Large diffs are not rendered by default.

942 changes: 280 additions & 662 deletions README.zh-CN.md

Large diffs are not rendered by default.

Binary file added docs/api-explorer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
135 changes: 135 additions & 0 deletions docs/en/migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
<!-- code_chunk_output -->

* [Changes in 2.0](#changes-in-20)
* [Remove the option controllerDir](#remove-the-option-controllerdir)
* [Remove the option port](#remove-the-option-port)
* [Remove the option server](#remove-the-option-server)
* [Remove the option versioning](#remove-the-option-versioning)
* [Remove the option apiExplorerPath](#remove-the-option-apiexplorerpath)
* [Remove the option apiExplorerStaticPath](#remove-the-option-apiexplorerstaticpath)
* [Remove the option validator](#remove-the-option-validator)
* [Remove the option jsonSchemaFormatters](#remove-the-option-jsonschemaformatters)
* [Remove the option errorHandler](#remove-the-option-errorhandler)
* [Remove the option defaultResponseSchemas](#remove-the-option-defaultresponseschemas)
* [Remove function router.apiExplorer()](#remove-function-routerapiexplorer)
* [Remove function router.apiExplorerV3()](#remove-function-routerapiexplorerv3)
* [Remove function router.use(keyword, fn)](#remove-function-routerusekeyword-fn)
* [Remove function router.extend(endpoint, fn)](#remove-function-routerextendendpoint-fn)

<!-- /code_chunk_output -->

[koa-router]: https://github.com/alexmingoia/koa-router
[oai-router-middleware]: https://github.com/oaijs/koa-oai-router-middleware
[oai-router-parameters]: https://github.com/oaijs/koa-oai-router-parameters
[oai-router-responses]: https://github.com/oaijs/koa-oai-router-responses
[oai-router-correction]: https://github.com/oaijs/koa-oai-router-correction
[oai-router-cache]: https://github.com/oaijs/koa-oai-router-cache
[oai-router-rbac]: https://github.com/oaijs/koa-oai-router-rbac
[references-plugin]: ./references.md#plugin

# Changes in 2.0
Sorry, 1.x can not be easily upgraded to 2.0 for the sake of simplicity, elegance, maintainability, and extendibility. I want to build a good project, to solve some of the problems we actually encounter better.

If you are using the following features, please migrate as the document says.

## Remove the option controllerDir
Middleware loader is no longer built-in, supported by [koa-oai-router-middleware][oai-router-middleware]. Please refer to the following code:
```js
const Koa = require('koa');
const Router = require('koa-oai-router');
const middleware = require('koa-oai-router-middleware');

const app = new Koa();

const router = new Router({
apiDoc: './api',
options: {
// Attention: `middleware` is name of plugin(defined by the plugin author),`./controllers` is controllerDir
// The key-value pairs in options pass the plug-in parameters to the plug-in based on the plug-in name when the plug-in is called.
middleware: './controllers',
},
});

router.mount(middleware());

app.use(router.routes());

app.listen(3000);
```
Or
```js
const Koa = require('koa');
const Router = require('koa-oai-router');
const middleware = require('koa-oai-router-middleware');

const app = new Koa();

const router = new Router({
apiDoc: './api',
});

// Attention: Configure the middleware directory when the plug-in is mounted
router.mount(middleware('./controllers'));

app.use(router.routes());

app.listen(3000);
```

## Remove the option port
No longer output api-explorer visit address on console, visit: `http://{ip}:{port}/api-explorer`

## Remove the option server
No longer output api-explorer visit address on console, visit: `http://{ip}:{port}/api-explorer`

## Remove the option versioning
Disabled, It can be implemented by the API description `basePath`. api doc:
```yaml
swagger: '2.0'
info:
version: 1.0.0
title: Swagger Petstore
description: >-
A sample API that uses a petstore as an example to demonstrate features in
the swagger-2.0 specification
termsOfService: 'http://swagger.io/terms/'
contact:
name: Swagger API Team
license:
name: MIT
basePath: /v1/api
...
...
```

## Remove the option apiExplorerPath
No longer provide customized api-explorer path function, visit: `http://{ip}:{port}/api-explorer`

## Remove the option apiExplorerStaticPath
No longer supported.

## Remove the option validator
Form validation is no longer built-in, supported by [koa-oai-router-parameters][oai-router-parameters].

## Remove the option jsonSchemaFormatters
Form validation `JSON-Schema formatters` configuration features, supported by [koa-oai-router-parameters][oai-router-parameters].

## Remove the option errorHandler
Error handler is no longer built-in, supported by [koa-oai-router-responses][oai-router-responses].

## Remove the option defaultResponseSchemas
Error handler `Response Schemas` configuration features is no longer built-in, supported by [koa-oai-router-responses][oai-router-responses].

## Remove function router.apiExplorer()
No longer supported swagger-ui 2.x `api-explorer`.
There is no need to mount, it can be control by `apiExplorerVisible`.

## Remove function router.apiExplorerV3()
There is no need to mount, it can be control by `apiExplorerVisible`.

## Remove function router.use(keyword, fn)
Please use the new way to mount [Plugin][references-plugin], if the plugin is not supported, please give me an issue.

## Remove function router.extend(endpoint, fn)
No longer supported.
170 changes: 170 additions & 0 deletions docs/en/references.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
<!-- code_chunk_output -->

* [Router](#router)
* [new Router(options)](#new-routeroptions)
* [router.mount(Plugin)](#routermountplugin)
* [router.get|put|post|patch|delete|del](#routergetputpostpatchdeletedel)
* [router.routes()](#routerroutes)
* [router.use([path], middleware)](#routerusepath-middleware)
* [router.allowedMethods([options])](#routerallowedmethodsoptions)
* [router.redirect(source, destination, [code])](#routerredirectsource-destination-code)
* [router.route(name)](#routerroutename)
* [router.url(name, params, [options])](#routerurlname-params-options)
* [router.param(param, middleware)](#routerparamparam-middleware)
* [Router.url(path, params)](#routerurlpath-params)
* [Plugin](#plugin)
* [new Plugin(options)](#new-pluginoptions)

<!-- /code_chunk_output -->

[router-verbs]: https://github.com/alexmingoia/koa-router#routergetputpostpatchdeletedel--router
[router-routes]: https://github.com/alexmingoia/koa-router#routerroutes--function
[router-use]: https://github.com/alexmingoia/koa-router#routerusepath-middleware--router
[router-allowmethods]: https://github.com/alexmingoia/koa-router#routerallowedmethodsoptions--function
[router-redirect]: https://github.com/alexmingoia/koa-router#routerredirectsource-destination-code--router
[router-route]: https://github.com/alexmingoia/koa-router#routerroutename--layer--false
[router-url]: https://github.com/alexmingoia/koa-router#routerurlname-params-options--string--error
[router-param]: https://github.com/alexmingoia/koa-router#routerparamparam-middleware--router
[Router-url]: https://github.com/alexmingoia/koa-router#routerurlpath-params--string
[oai-fields]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-5

# Router
Inherited from [koa-router](https://github.com/alexmingoia/koa-router), in addition to that the `prefix` option is not supported temporarily, to maintain other original function, features and performance. And some new features added.

## new Router(options)

* `options` {object} configuration options. Can have the following fields:
* `apiDoc` {string} `required` api document or document directory. When the api document is directory, it will load other files in the directory automatically.
* `apiExplorerVisible` {boolean} `optional` enable `api-explorer`. default `true`.
* `options` {object} `optional` plugin options. `key` is plugin name, `value` is plugin arguments.

`apiDoc` document can be yaml or json format. When `apiDoc` is a directory, the contents of each api file description directory will be merged into the OpenAPI protocol file. The contents of `/project/paths` will be loaded into the `paths` field of the document, the contents of `/project/definitions` will be loaded into the document's `definitions` field, and the other folders will not be loaded.

api document directory structure is as follows:
* `project`
* `api.yaml`
* `paths`
* `definitions`
* `parameters`
* `responses`
* `securityDefinitions`
* `security`
* `tags`
* `externalDocs`

There is no need to use any plugins if you only want to use the basic functionality of the router and `api-explorer`. You just need to configure ` apiDoc` and `apiExplorerVisible`. route and middleware need to be bound manually. Here is the code:
```js
const Koa = require('koa');
const Router = require('koa-oai-router');

const app = new Koa();

const router = new Router({
apiDoc: './api',
apiExplorerVisible: true,
});

// Manually mount /hello with business middleware
router.get('/hello', (ctx, next) => {
ctx.response.body = 'world';
});

app.use(router.routes());

app.listen(3000);
```

## router.mount(Plugin)
Mount the plugin to the router, the plugin will be executed with order of mount.
If one of the plugins does not evoke next(), execution of the subsequent plugin chain will be terminated.

## router.get|put|post|patch|delete|del
Same as koa-router: [router.get|put|post|patch|delete|del][router-verbs]

## router.routes()
Same as koa-router: [router.routes()][router-routes]

## router.use([path], middleware)
Same as koa-router: [router.use([path], middleware)][router-use]

## router.allowedMethods([options])
Same as koa-router: [router.allowedMethods([options])][router-allowmethods]

## router.redirect(source, destination, [code])
Same as koa-router: [router.redirect(source, destination, [code])][router-redirect]

## router.route(name)
Same as koa-router: [router.route(name)][router-route]

## router.url(name, params, [options])
Same as koa-router: [router.url(name, params, [options])][router-url]

## router.param(param, middleware)
Same as koa-router: [router.param(param, middleware)][router-param]

## Router.url(path, params)
Same as koa-router: [Router.url(path, params)][Router-url]


# Plugin
Plugins can be applied to every api as koa middleware.
Its activation depends on whether the api document contains its activation `field`. Once the plugin is activated, `middlewareWrapper` will be invoked internally and passed in the `(middlewareOpts, middlewareArgs)` parameter and must return a koa middleware that will be mounted on the current api.

## new Plugin(options)
Create a plugin.

* `options` {object} Plugin configuration options. Can have the following fields:
* `name` {string} `required` The name of the plugin. Configure the plugin parameters in the router options as the key.
* `field` {string|string[]} `required` Activate field. The plugin is activated when this field is included in the API document. Field range reference [Operation Object][oai-fields].
* `middlewareWrapper` {object} `required` Plugin logic module, you must return a koa middleware.
* `middlewareArgs` {object} `optional` Plugin global options.

`middlewareWrapper` Must return a koa middleware, there (middlewareOpts, middlewareArgs) Parameters:
* `middlewareOpts` {object} Information about the current interface document fragment when the plug-in is activated.
* `endpoint` {string} ednpoint
* `field` {string} the keyword when activated
* `fieldValue` {object} The data corresponding to the keyword when it is activated
* `operation` {string} http method
* `operationValue` {object} api's meta data
* `middlewareArgs` {any} Plugin global options.

`middlewareArgs` can be configured when creating a router and the configuration of this method will have the highest priority.
```js
const plugin = new PluginXXX({
name: 'pluginXXX',
field: 'parameters',
// middlewareArgs: pluginArgs,
middlewareWrapper: () => {
return (ctx, next) => {return next();};
},
});

const router = new Router({
apiDoc: './api',
options: {
pluginXXX: pluginArgs,
}
});

router.mount(plugin);
```

`middlewareArgs` it can also be configured when creating a plugin, and the method's configuration will have the lowest priority.

```js
const plugin = new PluginXXX({
name: 'pluginXXX',
field: 'parameters',
middlewareArgs: pluginArgs,
middlewareWrapper: () => {
return (ctx, next) => {return next();};
},
});

const router = new Router({
apiDoc: './api',
});

router.mount(plugin);
```
1 change: 1 addition & 0 deletions docs/en/usage-guides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
TODO
Loading

0 comments on commit f91fd9e

Please sign in to comment.