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如下
    java生成API文档_第1张图片

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

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

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

使用方法如下:

  1. 在IDEA上安装apiDoc插件。在Plugins中搜索apiDoc,选择安装(我这里已经安装完了)java生成API文档_第3张图片

  2. 在方法名称上右键选择apiDocjava生成API文档_第4张图片

  3. 生成注解,插件会依据实体(以及实体属性注释)生成注解。java生成API文档_第5张图片

  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":{}}
     */
    

你可能感兴趣的:(JAVA)