# xxd-smartdoc-middleware > It's an project specific version, maybe not suitable for other projects. Latest version **1.0.21** (published 2020-04-23) · ISC license · 0 weekly downloads ## Install ```sh npm install xxd-smartdoc-middleware pnpm add xxd-smartdoc-middleware yarn add xxd-smartdoc-middleware bun add xxd-smartdoc-middleware ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.0.21 | | Published | 2020-04-23 | | First published | 2017-11-10 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 6 | | Unpacked size | 7.4 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | linkeo | ## Links - npm: https://www.npmjs.com/package/xxd-smartdoc-middleware - Repository: https://github.com/linkeo/xxd-smartdoc-middleware - Homepage: https://github.com/linkeo/xxd-smartdoc-middleware#readme - Issues: https://github.com/linkeo/xxd-smartdoc-middleware/issues - npm.io page: https://npm.io/package/xxd-smartdoc-middleware ## Dependencies (6) - [klaw](https://npm.io/package/klaw.md) ^3.0.0 - [debug](https://npm.io/package/debug.md) ^4.1.1 - [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.3 - [koa-send](https://npm.io/package/koa-send.md) ^5.0.0 - [lodash.flatten](https://npm.io/package/lodash.flatten.md) ^4.4.0 - [lodash.difference](https://npm.io/package/lodash.difference.md) ^4.5.0 ## Recent versions - 1.0.21 (latest) — 2020-04-23 - 1.0.20 — 2020-04-23 - 1.0.19 — 2020-04-23 - 1.0.18 — 2020-04-23 - 1.0.17 — 2020-04-22 - 1.0.16 — 2020-04-22 - 1.0.15 — 2020-04-22 - 1.0.14 — 2020-04-20 - 1.0.13 — 2020-03-09 - 1.0.12 — 2020-03-09 - 1.0.11 — 2020-03-06 - 1.0.10 — 2019-11-25 - 1.0.9 — 2019-11-25 - 1.0.8 — 2019-11-25 - 1.0.7 — 2019-11-25 - … 14 more at https://npm.io/package/xxd-smartdoc-middleware/versions ## README # Smartdoc Middleware (For XXD) v1.x \* It's an project specific version, maybe not suitable for other projects. ## Usage ```bash npm i koa-mount xxd-smartdoc-middleware@^1 ``` ```js 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. --- _Source: https://npm.io/package/xxd-smartdoc-middleware · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._