介绍

一般，我们使用Springfox生成swagger api文档，但Springfox不支持从javadoc中生成，只能通过注解的方式标注文档。

这样，当共享一些POJO类时，为了同时生成javadoc文档和swagger文档，需要重复写两份。

此外，当使用swagger注解时，一般如下使用：

@ApiParam(name="parameterA",value="参数A")

public void path(@PathVariable String parameterA, String parameterB)

其中，name指定了参数的名字，这种通过字符串的方式没有IDE的重构支持。

而通过javadoc指定的方式有IDE的重构支持，当重命名变量名时，会一起修改javadoc中的变量名。

如：

/**

* path 变量

* @param parameterA 参数A

* @param parameterB 参数B

*/

@PostMapping("/path/{parameterA}/{parameterB}")

public void path(@PathVariable String parameterA, String parameterB)

{

}

通过使用RestDoc库，代码如下：

/**

* body 里的复杂对象

*/

@PostMapping("/body/complex")

public void complex(@RequestBody ParameterA obj)

{

}

/**

* path 变量

* @param parameterA 参数A

* @param parameterB 参数B

*/

@PostMapping("/path/{parameterA}/{parameterB}")

public void path(@PathVariable String parameterA, String parameterB)

{

}

效果如下：

使用

第一步，配置pom，配置RestDocConfig

在SpringBoot中，增加依赖：

cn.willingxyz.restdoc

RestDocSpringSwagger3

0.2.0.0-beta1

对于JavaConfig，配置如下：

@Bean

RestDocConfig _swaggerConfig()

{

return RestDocConfig.builder()

.apiTitle("rest doc title")

.apiDescription("rest doc desc")

.apiVersion("api version")

// .fieldPrefix("_")

.packages(Arrays.asList(""))

.build();

}

其中 packages 表示要扫描的基础包名，如 packages(Arrays.asList("cn.willingxyz.restdoc.springswagger3.examples"))

其中 fieldPrefix表示字段前缀。

因为在获取javadoc时，会从field、get方法、set方法上获取，因此如果field有前缀，需要通过fieldPrefix设置，否则将无法获取到javadoc。

如：

public class Response {

/**

* name javadoc

*/

private String _name;

public String getName() {

return _name;

}

public void setName(String name) {

_name = name;

}

}

Name属性对应的字段是_name，因此 fieldPrefix应该设置为 .fieldPrefix("_")

第二步，在需要生成javadoc的项目中，增加如下依赖：

com.github.therapi

therapi-runtime-javadoc-scribe

0.9.0

provided

具体可参考 RestDocSpringExamples。

原理

通过注解处理器在编译时生成javadoc的json文件。

在运行时读取生成的javadoc文件。