在运行时通过javadoc生成Swagger API文档的库

介绍

一般，我们使用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)
    {
    }

效果如下：

example_summary.png

使用

仓库地址：https://github.com/Willing-Xyz/RestDoc
在线示例：http://www.willingxyz.cn:8084/swagger-ui/index.html

第一步，配置pom，配置RestDocConfig

在SpringBoot中，增加依赖：

<dependency>
     <groupId>cn.willingxyz.restdoc</groupId>
     <artifactId>RestDocSpringSwagger3</artifactId>
     <version>0.1.0</version>
 </dependency>

对于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的项目中，增加如下依赖：

<!-- Annotation processor -->
<dependency>
    <groupId>com.github.therapi</groupId>
    <artifactId>therapi-runtime-javadoc-scribe</artifactId>
    <version>0.9.0</version>
    <scope>provided</scope>
</dependency>

启动应用后，打开 http://host/swagger-ui/index.html 浏览

具体可参考 RestDocSpringSwagger3Examples。

原理

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