推薦一款在運行時經過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文件。