Node 项目使用注入 API 文档实践
为什么需要 API 文档
目前大的环境下面,基本服务都以单体服务转换成前后端分离的服务,客户端作为调用方,服务端作为提供方需要给予到调用方通俗易懂的文档。
常见 API 文档有哪些
Modern documentation format and toolchain using Git and Markdown
- Usage
- 优点:
- 类似书籍的管理方式(适合写书)
- 支持多人协作,支持保存在 Github 中
- 支持 Build 成静态网页,部署方便
- 缺点:
- 需要熟悉 Markdown 语法,不是实时生成,需要使用 Git-cli 打包文件
- 以一本书籍作为起点,只能放到单个项目中
- 总结:适合写书籍,不太适合 API 开发文档
An API documentation generator for JavaScript.
- Usage
- 优点:
- 功能丰富,支持引入块状注释(Block Tags)
- 功能丰富,支持内联注释(Inline Tags)
- 强大的社区支持,各个平台支持 jsdocs 插件
- 缺点:
- 有一定的学习成本,需要学习它的块状注释使用方式
- UI 只能单项目使用,每个项目的 DOC UI 独立
- 在线样例(better-docs tui-jsdoc-template)
- 总结:适合深度定制项目,比如说我们对外开放 API 给开发者使用。
Generates swagger doc based on JSDoc.
- Usage
- 优点:
- 集合 Swagger,支持按照类似 JSDoc 方式生成文档
- 支持错误定位,如果注释书写错误,能够抛出具体的错误栈
- 支持 CLI,自由选择文件输出位置
- 缺点:
- 书写格式不友好,强格式要求,对于新手来说不容易上手,官方样例较少,很多语法需要对于 Swagger YAML 格式,自己理解进行映射
- 没有能够完成安装 JSDoc 格式来书写注释,更倾向于 YAML 文件
simple generator handler for swagger
/**
* @typedef Product
* @property {integer} id
* @property {string} name.required - Some description for product
* @property {Array.<Point>} Point
*/
/**
* This function comment is parsed by doctrine
* sdfkjsldfkj
* @route POST /users
* @param {Point.model} point.body.required - the new point
* @group foo - Operations about user
* @param {string} email.query.required - username or email
* @param {string} password.query.required - user's password.
* @param {enum} status.query.required - Status values that need to be considered for filter - eg: available,pending
* @operationId retrieveFooInfo
* @produces application/json application/xml
* @consumes application/json application/xml
* @returns {Response.model} 200 - An array of user info
* @returns {Product.model} default - Unexpected error
* @returns {Array.<Point>} Point - Some description for point
* @headers {integer} 200.X-Rate-Limit - calls per hour allowed by the user
* @headers {string} 200.X-Expires-After - date in UTC when token expires
* @security JWT
*/
- Usage
- 优点:
- 支持集成 Swagger,支持按照类似 JSDoc 方式生成文档
- 友好的文档的注释,贴合 IDE 函数注释
- 缺点:
- 实现可用的基础上,需要支持到 IDE,方便一键生成,支持自动化
Example
/**
* verify quarantine site
* @route POST /ui/quarantine/v1/verify_od_dedicated_quarantine_site
* @group quarantine
* @param {QuarantineJSON.model} body.body.required - post body
* @returns {object} 200 - An array of handler info
* @returns {Error} 400 - invalid site
* @returns {Error} 500 - internal error
*/
/**
* JSON parameters require a model. This one just has "name"
* @typedef QuarantineJSON
* @property {string} site.required - quarantine site info
*/
server.post('/ui/quarantine/v1/verify_od_dedicated_quarantine_site', middleware.other.verifyLoginInfo,
rbac.quarantine.write, quarantine.verifyOdDedicatedQuarantineSite);
/**
* HTTP API statistics
* @route GET /monit/v1/metric
* @group monit
* @param {string} sort.query - asc | desc
* @param {string} direction.query - count | avarageMillisecondCost | routeName
* @returns {object} 200 - An array of user info
* @returns {metrics.model} default - Unexpected error
*/
/**
* @typedef metrics
* @property {string} routeName.required - 'getuiadminv1company_plans'
* @property {number} count.required - route invoke times
* @property {number} avarageMillisecondCost.required - route avg second cost
*/
server.get("/monit/v1/metric", validator.query({
type: 'object',
properties: {
sort: { type: 'string', enum: ['count'] },
direction: { type: 'string', enum: ['asc', 'desc'] }
}
}), monitService.apiMetricHandlers);
项目地址:https://github.com/SensitiveMix/doc-generators 喜欢的同学请点个 Star