一、参考文章
https://blog.youkuaiyun.com/forezp/article/details/71023579
1、安装node.js
2、安装api.doc,它的项目源码:https://github.com/apidoc/apidoc 。
npm install apidoc -g
3、controller层请求路径写法
import org.springframework.web.bind.annotation.*;
/**
* 先安装node.js
* 在安装apidoc
* Created by fangzhipeng on 2017/4/17.
*/
@RestController
@RequestMapping(value = "/user")
public class UserController {
/**
* @api {get} /user/:id 获取用户信息
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
@RequestMapping (value = "/{id}",method = RequestMethod.GET)
public String getUser(@PathVariable(name = "id")long id){
return "用户id为"+id;
}
/**
* @api {POST} /login 用户登录
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用于用户登录
* @apiParam {String} userName 用户名
* @apiParam {String} password 密码
* @apiParamExample {json} 请求样例:
* ?userName=张三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} user 用户信息
* @apiSuccess (200) {String} userId 用户id
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
*/
/**
* @api {POST} /users/:id 修改(完善)用户信息
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 修改(完善)用户信息
* @apiParam (200) {String} [name] 真实姓名
* @apiParam (200) {String} [mobile] 手机号
* @apiParam (200) {String} [birthday] 生日
* @apiParam (200) {String} [email] 邮箱
* @apiParam (200) {String} [summary] 简介
* @apiParam (200) {String} [idCardNo] 身份证号
* @apiParam (200) {String} [address] 家庭住址
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"修改成功"}
*/
}
主要字段就是:
@api {method} path [title] method:请求方法, path:请求路径 title(可选):标题
步骤1:
在项目的主目录新建一个apidoc.json文件:
步骤2:
先cd到工程的外层目录,并在外层目建个输出文档的目录,我建的是docapi。
apidoc -i springboot-apidoc/ -o apidoc/
步驟3:
打开index.html,可以看到文档页面: