luyingqi / EasyRestDocs

easy rest doc for Spring boot

EasyRestDocs (Rest Docs Plus)

easy rest doc for Spring boot. 依赖spring AOP 发现 RestController 注解的 beans, 对其 RequestMapping 注解的 methods 进行解析, 生成 markdown 和 html 格式的文档.

用法

使用@EnableRestDocs注解启用自动生成, 包含name/version/usage三个属性, 生成在文档最前部分总体说明

注解

@RestDoc

可用于单独指定method的usage内容

@RestMethod

1. name 方法名
2. requestExampleClass 如果不为Void.class(默认值)则实例化并生成pretty json string作为接口请求body的样例
3. requestExampleText 如果requestExampleClass不存在,使用该属性作为接口请求body的样例
4. responseExampleClass 如果不为Void.class(默认值)则实例化并生成pretty json string作为接口输出样例
5. responseExampleText 如果responseExampleClass不存在,使用该属性作为接口输出样例
6. scopes 接口所属scope
7. usage 用途说明
8. errors (@RestError) 错误描述数组

@RestError

1. code 错误码
2. message 错误说明

参数

1. 跳过 HttpServletRequest/HttpServletRequest 等
2. 识别RequestParam注解的name/required等属性

@RestParam

1. name 参数名, 作为@RequestParam.name的fallback
2. description 参数作用描述

例子

1. 只扫描@RestController注解的类, 如果存在@RequestMapping并设置path, 会叠加到内部methods的uris

@RestController
@RequestMapping(value = { "/1", "/2" })
public class DemoRestApi {}

2. 生成response样例, 定义样例类, 通过@RestMethod注解指定

static public class ResponseExample {
    	int code;
    	String message;
    	
    	public String getMessage() {
			return message;
		}
}

@RestMethod(responseExampleClass = ResponseExample.class
    errors = {
        @RestError(code = -1, message = "bad")
    })
@RestDoc(usage = "api used to say hello to someone")
@RequestMapping(value = "/hello", method = {RequestMethod.GET})
public Object get(
        @RestParam @RequestParam(name = "who", defaultValue = "") String who
) {
    return "hello," + who;
}

3. 生成response样例, 需要@RequestBody和@RestMethod.requestExampleClass同时具备

输出文件

• 可通过 ${restdocs.base} 配置, 默认为 "/docs.md"
• 在访问路径后加 /html 能够看到 http://strapdownjs.com/ 渲染之后的html

TODOs:

1. 支持 @PathVariable
2. 支持 scopes
3. 更多完善