推荐一款在运行时经过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)
    {
    }

效果以下：

使用

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

第一步，配置pom，配置RestDocConfig

在SpringBoot中，增长依赖：

<dependency>
     <groupId>cn.willingxyz.restdoc</groupId>
     <artifactId>RestDocSpringSwagger3</artifactId>
     <version>0.2.0.0-beta1</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.... 浏览

具体可参考 RestDocSpringExamples。

原理

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