Apidoc 实践和自动化生成

在前后端分离框架中，API文档频繁交接。如果涉及到第三方接口调用，多方合作场景下，API和文档变更可能会更快。为了方便维护API和交接文档，这里给大家推荐一款文档生成工具 - apidoc

1.apidoc 简介

apidoc 是一个基于 nodejs 的 API 文档生成工具，从代码注释中提取特定格式的内容，生成API文档。目前支持的语言有：C#、C/C++、D、Erlang、Go、Groovy、Java、Javascript、Pascal/Delphi、Perl、PHP、Python、Rust、Ruby、Scala 和 Swift。特点：

• 跨平台，linux、windows、macOS 等都支持。
• 支持语言广泛。
• 支持文档版本管理。
• 支持多个不同语言的多个项目生成一份文档。
• 输出模板可自定义。
• @apiGroup name。分组名称，被解析为导航栏菜单
• @apiName name。接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
• @apiDescription text。接口描述，支持html语法
• @apiVersion verison。接口版本，major.minor.patch的形式
• @apiIgnore [hint]。apidoc会忽略使用@apiIgnore标注的接口，hint为描述
• @apiSampleRequest url。接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种
• @apiDefine name [title] [description]。定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块在@apiDefine内部不可以使用@apiUse
• @apiUse name。引入一个@apiDefine的注释块
• @apiParam [(group)] [{type}] [field=defaultValue] [description]。请求参数
• @apiHeader [(group)] [{type}] [field=defaultValue] [description]。头部参数
• @apiError [(group)] [{type}] field [description]。响应错误时参数
• @apiSuccess [(group)] [{type}] field [description]。成功时参数，group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
• @apiParamExample [{type}] [title] example。参数请求用例
• @apiHeaderExample [{type}] [title] example。头部请求用例
• @apiErrorExample [{type}] [title] example。错误请求用例
• @apiSuccessExample [{type}] [title] example。成功请求用例type表示的是example的语言类型， example内容会被直接解析显示。
• @apiPermission name。name必须独一无二，描述@api的访问权限，如admin/anyone
• 一种是单独使用一个文件或文件夹来写注释。
• https://github.com/shama/gaze
• https://github.com/apidoc/apidoc