Skip to content

apidoc

Jump to bottom
yangyp8110 edited this page Jan 17, 2018 · 1 revision

参考资料

安装node.js，如果没有安装，参考 node.js安装

项目根目录新建文件apidoc.json,footer.md,header.md

  • apidoc.json
{
  "name": "测试接口文档",
  "version": "1.0.1",
  "description": "测试接口文档Demo",
  "title": "apidoc示例",
  "url" : "http://local.test.com",
  "header": {
    "title": "使用须知",
    "filename": "header.md"
  },
  "footer": {
    "title": "关于",
    "filename": "footer.md"
  }
}
  • footer.md
<div class="alert alert-danger">
站点域名：local.test.com<br>
测试环境：120.0.0.1 local.test.com  端口：8090<br>
预发布环境：192.168.7.12   local.test.com   端口：空<br>
线上：local.test.com   端口：空<br>
<strong>如有问题请联系XXXX</strong><br>
</div>
  • header.md
<div class="alert alert-danger">
此文档仅供参考，如有问题概不负责<br>
Copyright © 1999-2017, local.test.com, All Rights Reserved <br>
</div>

api doc 示例(1.0.1与1.0.2版本共存)

    /**
     * @api {POST} /home/test 测试api
     * @apiName test
     * @apiGroup home
     * @apiVersion 1.0.1
     * @apiDescription 测试接口，只返回用户名
     *
     * @apiHeader (请求头) {String} Content-Type application/json;charset=UTF-8
     * @apiHeaderExample 请求头示例:
     * Content-Type: application/json;charset=UTF-8
     *
     * @apiParam (请求参数) {int} uId uId.
     *
     * @apiSuccess (返回参数) {int} resCode 1:成功； 其他失败.
     * @apiSuccess (返回参数) {String} resMessage  对应resCode的说明.
     * @apiSuccess (返回参数) {Object} resModel ResDto对象
     * @apiSuccess (返回参数 - ResDto对象) {decimal} uName userName
     *
     *
     * @apiSuccessExample 返回成功示例:
     *   HTTP/1.1 200 OK
     *   {
     *       "resCode": 1,
     *       "resMessage": "SUCCESS",
     *       "resModel": {
     *       "uName": "zhangsan"
     *       }
     *   }
     * @apiSuccessExample 返回失败示例:
     *   {
     *       "resCode": -1,
     *       "resMessage": "FAIL",
     *       "resModel": []
     *   }
     *
     */

    /**
     * @api {POST} /home/test 测试api
     * @apiName test
     * @apiGroup home
     * @apiVersion 1.0.2
     * @apiDescription 测试接口，返回用户名与对应的userId
     *
     * @apiHeader (请求头) {String} Content-Type application/json;charset=UTF-8
     * @apiHeaderExample 请求头示例:
     * Content-Type: application/json;charset=UTF-8
     *
     * @apiParam (请求参数) {int} uId uId.
     * @apiParam (请求参数) {String} uName (可选参数)userName
     *
     * @apiSuccess (返回参数) {int} resCode 1:成功； 其他失败.
     * @apiSuccess (返回参数) {String} resMessage  对应resCode的说明.
     * @apiSuccess (返回参数) {Object} resModel ResDto对象
     * @apiSuccess (返回参数 - ResDto对象) {decimal} uId uId
     * @apiSuccess (返回参数 - ResDto对象) {decimal} uName userName
     *
     *
     * @apiSuccessExample 返回成功示例:
     *   HTTP/1.1 200 OK
     *   {
     *       "resCode": 1,
     *       "resMessage": "SUCCESS",
     *       "resModel": {
     *       "uId": 375,
     *       "uName": "zhangsan"
     *       }
     *   }
     * @apiSuccessExample 返回失败示例:
     *   {
     *       "resCode": -1,
     *       "resMessage": "FAIL",
     *       "resModel": []
     *   }
     *
     */
    @RequestMapping("/test")
    public OutResponse<ResDto> test(@RequestBody InputRequest request){
        ResDto dto = new ResDto();
        dto.setuId(request.getuId());
        dto.setuName(request.getuName());
        OutResponse<ResDto> out = new OutResponse<>();
        out.setResCode(1);
        out.setResMessage("SUCCESS");
        out.setResModel(dto);
        return out;
    }

生成命令

apidoc -i dir1 -o dir2

  • dir1 是项目代码路径
  • dir2 是输出doc路径
Clone this wiki locally