Smartdoc Middleware (For XXD) v1.x

* It's an project specific version, maybe not suitable for other projects.

Usage

npm i koa-mount xxd-smartdoc-middleware@^1

const app = new Koa();
const smartdoc = require('xxd-smartdoc-middleware');
//...
const spec = require('./spec.json'); // The API specification of your web application
// const spec = require.resolve('./spec.json'); // Path to a JSON file is also acceptable
const prefix = '/docs'; // The prefix you want to serve smartdoc.
const docsDir = `${__dirname}/docs`; // The directory of markdown documents.
app.use(mount(prefix, smartdoc({ prefix, spec, docsDir })));

Note: Must use koa-mount instead of koa-router, because koa-mount will strip the prefix off but koa-router wont.

Options

• options.prefix: The prefix defined here will be treat as relative path of the document page from the api root.
• options.spec: API specification, describes your application, modules and actions.
• options.docs: The directory you put markdown documents, this module will parse them to generate the catalog and search index.

API Specification

ApplicationSpecification

| Field | Type | Description | | ----------- | --------------------- | ----------------------------------------------------------------- | | type | string | Must be "application" | | title | string | Display name of the application | | name | string | Inner name of the application, generally the name in package.json | | description | string | Description of the application, supports markdown | | notes | string[] | Notes of the application, supports markdown | | address | string | The url of the application | | contact | string | Contact messages of the developer. | | version | string | Version of the application, generally the version in package.json | | modules | ModuleSpecification[] | Modules in the application |

ModuleSpecification

| Field | Type | Description | | ----------- | ------------------------- | ------------------------------------------------------------ | | type | string | Must be "module" | | title | string | Display name of the module | | name | string | Inner name of the module, generally the name in package.json | | description | string | Description of the module, supports markdown | | notes | string[] | Notes of the module, supports markdown | | path | string | The path prefix of the module | | middlewares | MiddlewareSpecification[] | Middlewares applied to every actions of the module | | filename | string | Filename of the module | | actions | ActionSpecification[] | Actions of the module |

Note: According to the implementation of XXD:

• Path of module spec doesn't affect path of actions, but must be prefix of those paths.

ActionSpecification

| Field | Type | Description | | ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------- | | type | string | Must be "action" | | title | string | Display name of the module | | name | string | Inner name of the module, generally the name in package.json | | description | string | Description of the module, supports markdown | | notes | string[] | Notes of the module, supports markdown | | route.method | string | Request method of the action, one of "GET", "POST", "PUT", "DELETE","HEAD","OPTIONS","PATCH" | | route.path | string | Request path of the action, if module has prefix, route.path must be prefixed by that | | params | ParameterSpecification[] | Request parameters of the action | | middlewares | MiddlewareSpecification[] | Middlewares applied to the action | | filename | string | Filename of the module | | funcname | string | Function name of the action |

Note: According to the implementation of XXD:

• Path of module spec doesn't affect path of actions, but must be prefix of those paths.

ParameterSpecification

| Field | Type | Description | | ----------- | ------ | --------------------------------------------------------- | | type | string | Type of the parameter | | name | string | Name of the parameter, generally the name in package.json | | description | string | Description of the parameter, supports markdown |

Note: According to the implementation of XXD:

• Parameter can be transferred by route parameters, query, request body (if possible, support json, urlencoded)
• Type "Upload" is representing a multipart file parameter.
• Multipart body is only supported when an Upload parameter is declared in the action.
• There will be some "mismatch parameter" if a @param annotation cannot be parsed correctly, these will be ignored in this module.

MiddlewareSpecification

| Field | Type | Description | | ----- | ------ | -------------------------------------------------------------- | | name | string | Name of the parameter, generally the name in package.json | | args | string | Arguments of the parameter, in the same format of query string |

Note: According to the implementation of XXD:

• Args of middlewares is a querystring.