如何使用apidoc来自动更新API文档

最新推荐文章于 2022-07-24 16:56:03 发布
最新推荐文章于 2022-07-24 16:56:03 发布
阅读量2.2k 收藏 1
点赞数
分类专栏： node.js 文章标签： nodejs api 文档 apidoc
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u010570551/article/details/76785496
版权

如何使用apidoc来自动更新API文档

安装apidoc

使用nodejs来进行安装

npm install apidoc -g

在项目路径下创建apiodc.josn文件

项目结构
可以参考如下的格式来进行设置

{
  "name": "EnergyRiver API",
  "version": "1.0.0",
  "description": "EnergyRiver API 使用文档",
  "title": "EnergyRiver API 使用说明",
  "url" : "http://localhost/public/doc/index.html",
  "order": [
    "Index",
    "Get",
    "Post",
    "Update",
    "Delete",
    "Overview",
    "Comment"
  ],
  "header": {
    "title":"GENERAL",
    "filename": "src/main/webapp/public/doc/header.md"
  }

}

将如上文件保存到apidoc.josn文件

创建文档的header

由于我们一般会api的访问地址，因此我们可以选择把api文档放在webapp下面。header.md是用来作为整个文档页面的头部信息出现的。
在apidoc.json文件中，我们指定了filename=src/main/webapp/public/doc/header.md

方法注释模板

注意：一般为了保证文档格式不被编辑器更改，使用/*，而不是/**来开启注释,
但是/*开启的注释，是不能被识别的，所以，注释必须以/**开始,编写过程尽量不要使用IDE的格式化功能。

    /** 
     * @api {get} /build/getBuildingInfo 获取所有建筑单元的信息
     * @apiName getBuildingInfo
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              "code":  200,
     *              "data": "建筑单元实际数据数组",
     *              "total": "总共数量"
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": null,
     *       "total": 0
     *     }
     */
    @RequestMapping(value = "/getBuildingInfo")
    @ResponseBody
    public Map<String, Object> getBuilingInfo(HttpServletRequest request) throws Exception {
        // 从session拿到token，再解密得到userid
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);

        // 按照userID来显示该用户登录时显示的建筑
        Map<String, Object> map = new HashMap<>();
        List<BuildingInfo> buildingInfos;
        if (loginInfo != null) {
            Long userID = AuthUtil.getUserId(request);
            buildingInfos = buildingInfoService.getbuildingInfo(userID);
            map.put("code", 200);
            map.put("data", buildingInfos);
            map.put("total", buildingInfoService.getAllCount());
        } else {
            map.put("code", 401);
            map.put("data", null);
            map.put("total", 0);
        }
        return map;
    }

生成文档

可以使用gitbash，在项目根路径下执行

$ apidoc -i src/main/java/ -o src/main/webapp/public/doc/

如果没有报错的话，就可以执行在public/doc中看到生成的文件了。

api文档已经生成

访问文档

打开public/doc/index.html就可以访问了

访问结果

定制样式

可以更改public/doc/css/style.css的内容来自定义api页面的样式

附加一个完整的demo

package cn.b507.ssm.controller.Build;

import cn.b507.ssm.po.Build.BuildingInfo;
import cn.b507.ssm.po.Build.BuildingType;
import cn.b507.ssm.service.Build.BuildingInfoService;
import cn.b507.ssm.tool.token.AuthUtil;
import com.alibaba.fastjson.JSONObject;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * <p>
 * Title: BuildingInfoController
 * </p>
 * <p>
 * Description:与建筑单元信息相关的业务需求处理controller
 * </p>
 *
 * @version 1.0
 * @date 2017-4-17
 */
@Controller
@RequestMapping("/build")
public class BuildingInfoController {
    @Autowired
    private BuildingInfoService buildingInfoService;

    /**
     * @api {get} /build/getBuildingInfo 获取所有建筑单元的信息
     * @apiName getBuildingInfo
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              "code":  200,
     *              "data": "建筑单元实际数据数组",
     *              "total": "总共数量"
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": null,
     *       "total": 0
     *     }
     */
    @RequestMapping(value = "/getBuildingInfo")
    @ResponseBody
    public Map<String, Object> getBuilingInfo(HttpServletRequest request) throws Exception {
        // 从session拿到token，再解密得到userid
        Long userID;
        if(request.getParameter("userID")!=null)
            userID = Long.parseLong(request.getParameter("userID"));
        else
            userID = AuthUtil.getUserId(request);
        Map<String,Object>map = new HashMap<>();
        if (userID != null) {
            List<BuildingInfo> buildingInfos = buildingInfoService.getbuildingInfo(userID);
            map.put("code", 200);
            map.put("data", buildingInfos);
            map.put("total", buildingInfoService.getAllCount(userID));
        } else {
            map.put("code", 401);
            map.put("data", null);
            map.put("total", 0);
        }
        return map;
    }

    /**
     * @api {get} /build/getBuildingInfoByID 根据建筑id来查询建筑的信息
     * @apiName getBuildingInfoByID
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {Number} buildingID 某个建筑单元的id
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              "code": 200,
     *              "data": "建筑单元实际数据数组"
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": null
     *     }
     */
    @RequestMapping(value = "/getBuildingInfoByID")
    @ResponseBody
    public Map<String, Object> getBuildingInfoByID(HttpServletRequest request,
                                                   Long buildingID) throws Exception {
        // 从session拿到token，再解密得到userid
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
        // 按照userID来显示该用户登录时显示的建筑
        BuildingInfo buildingInfos;
        Map<String, Object> map = new HashMap<>();
        if (loginInfo != null) {
            buildingInfos = buildingInfoService
                    .getBuildingInfoByBuildingID(buildingID);
            map.put("code", 200);
            map.put("data", buildingInfos);
        } else {
            map.put("code", 401);
            map.put("data", null);
        }
        return map;
    }

    /**
     * @api {get} /build/updateBuildingInfo 根据建筑id来修改建筑的信息
     * @apiName updateBuildingInfo
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {String} buildingInfo 某个建筑单元的更新后的信息
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              "code": 200,
     *              "result": true/false
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": false
     *     }
     */
    @RequestMapping(value = "/updateBuildingInfo")
    @ResponseBody
    public Map<String, Object> getBuildingInfoByID(HttpServletRequest request,
                                                   String buildingInfo) throws Exception {
        // 从session拿到token，再解密得到userid
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
        // 按照userID来显示该用户登录时显示的建筑
        Boolean result;
        Map<String, Object> map = new HashMap();
        if (loginInfo != null) {
            result = buildingInfoService.updateBuildingInfo(buildingInfo);
            map.put("code", 200);
            map.put("result", result);

        } else {
            map.put("code", 401);
            map.put("result", false);
        }
        return map;
    }

    /**
     * @api {get} /build/getUpperBuilding 获取上级建筑的相关信息
     * @apiName getUpperBuilding
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {String} upperBuilding 上级建筑单元的json数据信息
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              "code": 200,
     *              "result": true/false
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": false
     *     }
     */
    @ResponseBody
    @RequestMapping(value = "/getUpperBuilding", produces = "application/json;charset=UTF-8")
    public String getUpperBuilding(HttpServletRequest request,
                                   String upperBuilding) throws Exception {
        JSONObject jsonObject = JSONObject.parseObject(upperBuilding);
        return jsonObject.toJSONString();
    }

    /**
     * @api {get} /build/saveChildBuildInfo 保存下级建筑的添加信息
     * @apiName saveChildBuildInfo
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {String} childBuild 下级建筑单元的json数据信息
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              “code": 200,
     *              "result": true/false
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": false
     *     }
     */
    @ResponseBody
    @RequestMapping(value = "/saveChildBuildInfo")
    public Map<String, Object> saveChildBuildInfo(HttpServletRequest request,
                                                  String childBuild) throws Exception {
        // 从session拿到token，再解密得到userid
        Map<String, Object> map = new HashMap();
        Long userID = AuthUtil.getUserId(request);
        if (userID != null) {
            // 利用创建人和下级建筑信息添加下级建筑
            childBuild = childBuild.substring(1, childBuild.length() - 1);//去除引号
            childBuild = childBuild.replace("\\", "");
            boolean result = buildingInfoService.addChildBuild(userID, childBuild);

            map.put("code", 200);
            map.put("result", result);
        } else {
            map.put("code", 401);
            map.put("result", false);
        }
        return map;
    }

    /**
     * @api {get} /build/deleteBuild 删除建筑
     * @apiName deleteBuild
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {Number} buildingID 建筑单元ID
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              “code": 200,
     *              "result": true/false
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": false
     *     }
     */
    @ResponseBody
    @RequestMapping(value = "/deleteBuild")
    public Map<String, Object> deleteBuild(HttpServletRequest request, Long buildingID) throws Exception {
        // 从session拿到token，再解密得到userid
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
        Map<String, Object> map = new HashMap();
        // 按照userID来显示该用户登录时显示的建筑
        //Boolean result;
        if (loginInfo != null) {

            boolean result = buildingInfoService.deleteBuildingInfo(buildingID);
            map.put("code", 200);
            map.put("result", result);
        } else {
            map.put("code", 401);
            map.put("result", false);
        }
        return map;
    }

    /**
     * @api {get} /build/setLngAndLat 将建筑位置的地图坐标（经度，纬度）保存
     * @apiName setLngAndLat
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiParam {String} coordinate 经纬度信息json数据
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              “code": 200,
     *              "result": true/false
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *       "code": 401,
     *       "data": false
     *     }
     */
    @ResponseBody
    @RequestMapping(value = "/setLngAndLat", produces = "application/json;charset=UTF-8")
    public Map<String, Object> setLngAndLat(HttpServletRequest request, String coordinate) throws Exception {

        // 从session拿到token，再解密得到userid
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
        Map<String, Object> map = new HashMap();
        if (loginInfo != null) {
            // 将地图坐标（经纬度）保存入建筑信息
            boolean result = buildingInfoService.saveLngAndLat(coordinate);
            map.put("code", 200);
            map.put("result", result);
        } else {
            map.put("code", 401);
            map.put("result", false);
        }
        return map;
    }

    /**
     * @api {get} /build/getBulidInfoByUser 获取用户所在机构对应的建筑单元
     * @apiName getBulidInfoByUser
     * @apiGroup  build
     * @apiVersion 1.0.0
     *
     * @apiSuccessExample {json} Success-Response:
     *      HTTP/1.1 200 OK
     *      [
     *          {
     *              json数据
     *          }
     *      ]
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 401 UNAUTHORIZED
     *     {
     *          null/[]
     *     }
     */
    @RequestMapping(value = "/getBulidInfoByUser", produces = "application/json;charset=UTF-8")
    @ResponseBody
    public List<BuildingInfo> getBulidInfoByUser(HttpServletRequest request) throws Exception {

        //从session拿到token，再解密得到userid
        Long userID = AuthUtil.getUserId(request);
        List<BuildingInfo> buildingInfos = buildingInfoService.getBuildInfoByUser(userID);

        return buildingInfos;
    }

   /**
    * @api {get} /build/getALLbuilingType 获取所有的建筑类型
    * @apiName getALLbuilingType
    * @apiGroup  build
    * @apiVersion 1.0.0
    *
    * @apiSuccessExample {json} Success-Response:
    *      HTTP/1.1 200 OK
    *      [
    *          {
    *              “code”: 200,
    *              "data": "json数据"
    *          }
    *      ]
    * @apiErrorExample {json} Error-Response:
    *     HTTP/1.1 401 UNAUTHORIZED
    *     {
    *          “code”: 401,
    *          "data": null
    *     }
    */
    @RequestMapping(value = "/getALLbuilingType")
    @ResponseBody
    public Map<String, Object> getALLbuilingType(HttpServletRequest request) throws Exception {
        Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
        Map<String, Object> map = new HashMap();
        if (loginInfo != null) {
            List<BuildingType> buildingTypes = buildingInfoService.getALLbuilingType();
            map.put("code", 200);
            map.put("data", buildingTypes);
        } else {
            map.put("code", 401);
            map.put("data", null);
        }
        return map;
    }

    public BuildingInfoService getBuildingInfoService() {
        return buildingInfoService;
    }

    public void setBuildingInfoService(BuildingInfoService buildingInfoService) {
        this.buildingInfoService = buildingInfoService;
    }

}
Edocevol
关注
  • 0
    点赞
  • 踩
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
html api doc 模板,使用apidoc生成实用炫酷吊炸天的api文档
weixin_39707478的博客
06-22 653
为什么要用apidocapidoc根据其自定义注释语法自动生成api文档，我们只需要把代码中的注释按照其语法来写就能生成需要的文档，不需要手动写markdown。apidoc生成的文档相比markdown，漂亮直观又实用。如果API需要修改或者更新，直接修改代码的注释中即可。apidoc核心思路，文档与代码合一，修改代码就是修改文档，方便又实用。可以配合grunt使用，使自动化生成文档更加智能，支...
apidoc接口文档的自动更新与发布
爱码少年 00fly.online 的博客
02-24 5095
最近忙于某开源项目的接口文档整理，采用了apidoc来整理生成接口文档。apidoc是一个可以将源代码中的注释直接生成api接口文档的工具,对现有代码无侵入。他可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go…，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。下面我们以项目为例来展示如何实现接口文档的自动更新与发布。
基于 apidoc 生成在线接口文档 （实时更新）（linux系统）
成辉的博客
03-23 1978
基于 apidoc 生成在线接口文档 （实时更新）（linux系统） 动态加载，热部署 背景： 规范开发人员的接口文档 文档统一管理，防止本地文档版本不统一 远程部署，保证文档的统一性 主要还是解决，不用每个人去装一套环境 缺点： 1. 容错性太垃圾，可以优化 2. 需要一台服务器 3. 没有测试过多人操作 备注： 如若不想使用，远程文档连接的话，可以本地安装node.js 和 apidoc 本地...
apidoc模板
weixin_34261739的博客
12-27 656
2019独角兽企业重金招聘Python工程师标准>>> ...
ApiPost使用教程
qq_41780297的博客
07-24 2万+
学习下国产工具中接口测试工具，大赞，感觉比较好用，哈哈
apidoc的使用和常见问题的解决办法
small_33的博客
08-15 8997
珊妹子刚入职新公司就接触到apidoc这个生成接口文档的技术，刚刚学习的时候，它本身是有手册的，但是也是就介绍安装和语法，实际遇到的问题，还得自己来抠，这个apidoc是通过后台写接口的注释来达到自动生成接口文档的作用。 apidoc是基于node使用的，所以具体安装方法请参考：https://www.cnblogs.com/minsons/articles/7154090.html 安装和使...
apidoc自定义 标签|参数
Areom个人博客
09-04 765
这里自定义一个 apiAuthor - 开发者 第一步：首先在找到你的apidoc安装目录，我这里是： C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\ 注：以下目录都是以这个为跟目录。 第二步：找到定义文件： .\node_modules\apidoc-core\lib\index.js 第三步：添加...
apiDoc:RESTful Web API 文档生成器-开源
08-07
apiDoc 根据源代码中的 API 注释创建文档... 默认情况下，生成的 apiDoc 使用支持版本控制的复杂模板来查看 API 的不同版本，并比较以查看 API 的两个版本之间的更改。 您可以创建自己的模板并使用 apiDoc 生成的文件。
apidoc生成api文档
最新发布
04-10
apidoc是一款强大的API文档生成工具，它允许开发者通过在代码注释中添加特定的指令来自动构建清晰、结构化的API文档。这个工具极大地简化了API文档的维护过程，确保了文档与代码的一致性，降低了团队协作中的沟通...
tp5框架开发的restful API接口自动生成文档源码.zip
04-07
对于自动文档生成，这通常涉及到API文档工具的使用，如apidoc.js或 Swagger。这些工具可以从注释或特定的规范文件中解析API的信息，自动生成易于理解和使用的文档。在TP5项目中，开发者可以在控制器方法上方添加注释...
APIDOC模板。。。。
02-03
APIDOC 生成 RestFul 接口文档模板。apidoc是一款可以有源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。
apidoc-template:apiDoc的更干净，更漂亮的模板
05-06
的漂亮模板 制作示例文档 > apidoc -i ./examples -f .route.js -o ./docs -t ./template
apidoc:前端 API 文档
04-20
为了提高效率和规范性，开发团队通常会使用自动化工具生成API文档，其中推荐的工具有： 1. **apidoc**：本压缩包中的apidoc-main可能就是apidoc的主文件，apidoc是一款基于注释生成文档的工具，开发者只需在代码中...
使用apidoc管理RESTful风格Flask项目接口文档方法
09-20
使用apidoc管理RESTful风格Flask项目接口文档的方法是一种高效且规范的方式，它可以帮助开发者创建清晰、结构化的API文档，方便团队协作和对外提供服务。本文将详细介绍如何使用apidoc与Flask结合来构建RESTful API...
【unity3d之UI界面学习】NGUI插件的导入步骤
17的博客
01-26 9010
首先将下载好的NGUI资源包（我下载的是3.11.4版本）导入到引擎中进行使用，在unity3d界面点击鼠标右键，弹出的菜单送选中import package，然后选择custom package（自定义资源包），弹出资源路径窗口，找到NGUI资源包所在的位置，单击“打开”按钮即可。   【注意】NGUI资源包的路径不要有中文，否则将导入失败。  单击“打开”按钮后，等待unit
【应用推荐】最近大火的Apifox & Apipost 上手体验与选型建议
云间月
06-04 3859
各位从事开发的朋友们想必最近都被两款api 管理神器Apifox & Apipost刷屏了，作为一名软件发烧友，我也是第一时间就下载安装了，不过一直没有深入使用，最近正好有时间把两款工具都折腾了一下，这里就给大家分享一下我的使用体验，如果大家在选择的时候犯难，可以适当参考。从产品定位和功能特点来说，两款工具几乎没什么区别。说的更直白一点，两款工具都是国内版的Postman ，更符合国人的操作习惯，上手难度也比Postman 低。软件的选型，首先要明白我们的需求到底在哪里，想借助软件实现什么样的功能。我们现
API工具--apifox、apipost、yapi的区别（对比）
IT利刃出鞘的博客
04-03 1万+
现在的Java Web项目大都是前后端分离的，需要的人员有：后端、前端、测试。这时，接口文档就特别重要。 本文介绍apifox、apipost、yapi这三款接口文档工具的区别。
使用apidoc 生成Restful web Api文档
热门推荐
Lincoln 的专栏
01-06 7万+
在项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是office工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下！ 该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！ 工具名称：apiDoc Git地址：https://github.com/apidoc/apidoc 项目地址：http://apidocjs
apidoc的介绍和使用
lvbaolin123的博客
09-26 2万+
apidoc是使用编写接口文档非常方便的，一种编写
git可以自动生成api接口文档吗
05-13
Git本身是一个版本控制工具，不会直接生成...这些工具可以与Git集成，让你在代码变更时自动更新API文档。同时，它们也可以与其他工具集成，如持续集成/持续交付（CI/CD）工具，以便在代码发布时自动生成和发布API文档。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值