docs: update documents to 2.0

split documents and update to 2.0

docs/en/migration.md

@@ -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.

docs/en/references.md

@@ -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);
+```

docs/en/usage-guides.md

@@ -0,0 +1 @@
+TODO