api-doc

1. 安装node

2. node.js 安装api.doc

npm install apidoc -g

3. 在项目的主目录新建一个apidoc.json文件

{
  "name": "AlphaPortalService接口文档",
  "version": "1.0.0",
  "description": "AlphaPortalService接口文档",
  "title": "AlphaPortalService接口文档3",
  "url" : "http://localhost:8080/alphaPortalService",
  "sampleUrl" : "http://localhost:8080/alphaPortalService"
}

4.给controller方法上添加注释

  /**
     * @api {method} path [title]
     * @apiGroup name
     * @apiVersion version
     * @apiDescription text  
     * @apiParam {String} account 请求样例
     * @apiParam {String} password 请求样例
     * @apiParam {String} mobile 请求样例
     * @apiParam {int} vip = 0  请求样例
     * @apiParam {String} [recommend] 请求样例
     * @apiParamExample {json} 请求样例
     * @apiSuccess (200) {String} msg 请求样例
     * @apiSuccess (200) {int} code 0 请求样例
     * @apiSuccessExample {json} 返回样例:
     * {"code": 200,"msg": "成功!","body": "hello"}
     */

5. 用apidoc命令生成文档界面

1. 在工程项目的外层目录建立输出文档目录：ex:apidoc
2. 输入命令：
   apidoc -i AlphaPortalService/ -o apidoc/  
3. -i 输入目录 -o 输出目录
4. AlphaPortalService为工程名
5. 打开index.html,可以看到文档页面

@RestController
public class Test1Controller {

    /**
     * @api {POST} /register 注册用户
     * @apiGroup Users
     * @apiVersion 1.0.0
     * @apiDescription 用于注册用户
     * @apiParam {String} account 用户账户名
     * @apiParam {String} password 密码
     * @apiParam {String} mobile 手机号
     * @apiParam {int} vip = 0  是否注册Vip身份 0 普通用户 1 Vip用户
     * @apiParam {String} [recommend] 邀请码
     * @apiParamExample {json} 请求样例：
     * ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     * @apiSuccessExample {json} 返回样例:
     * {"code":"0","msg":"注册成功"}
     */
    @PostMapping("/register")
    public R hello(@RequestParam("account") String account,
                        @RequestParam("password")  String password,
                        @RequestParam("mobile")  String mobile,
                        @RequestParam("vip")  int vip,
                        @RequestParam("recommend")  String recommend) {
        log.info("account:{},password:{},mobile:{},vip:{},recommend:{}", account, password, mobile, vip, recommend);
        return R.ok("hello");
    }
}

如下:

image.png

文档：

image.png

image.png