java生成API文档

最近想要对java项目自动生成API文档，发现一个工具apidoc。这个工具可以依据一定格式的注释生成相应的HTML格式API接口文档，具体可以参考apidoc的官网。

使用方法如下：

1. 安装命令

   npm install apidoc -g
   

2. 生成文档命令

   apidoc -i myapp/ -o apidoc/ 
   

   myapp是项目的文件夹，需要包含apidoc.json，以及含有接口注释的源码文件。apidoc是生成的HTML的存放文件夹。

3. apidoc.json文件

   {
     "name": "xxx项目",
     "version": "1.0.0",
     "description": "api文档",
     "title": "api文档",
     "url" : "http://127.0.0.1:8080",
     "sampleUrl":"http://127.0.0.1:8080"
   }
   

4. 生成的HTML如下
   

由此上的步骤便可以生成HTML格式的API文档。

同时也有一款能将apidoc的HTML转为Markdown文档，地址https://github.com/rigwild/apidoc-markdown

但是，如果手动输入注释未免过于麻烦。于是我在IDEA上发现了一个生成apido注释的插件apiDoc。
该插件的源码地址https://gitee.com/UnlimitedBladeWorks_123/apidoc-plugin-idea。

使用方法如下：

1. 在IDEA上安装apiDoc插件。在Plugins中搜索apiDoc，选择安装(我这里已经安装完了)

2. 在方法名称上右键选择apiDoc

3. 生成注解，插件会依据实体（以及实体属性注释）生成注解。

4. 生成的注释内容

   /**
    * @api {POST} /department/updateDepartment updateDepartment
    * @apiVersion 1.0.0
    * @apiGroup DepartmentController
    * @apiName updateDepartment
    * @apiDescription 更新部门信息
    * @apiParam (请求参数) {Number} depId 部门Id
    * @apiParam (请求参数) {String} depName 部门名称
    * @apiParamExample 请求参数示例
    * depId=8670
    * depName=zVppqCv
    *
    * @apiSuccess (响应结果) {Number} code 状态码
    * @apiSuccess (响应结果) {String} msg 状态信息
    * @apiSuccess (响应结果) {Object} data 返回数据
    * @apiSuccessExample 响应结果示例
    * {"msg":"wm","code":2427,"data":{}}
    */