swagger文檔規(guī)范的使用

作者一開始使用springfox接入springmvc，但是配置有點復(fù)雜。后來轉(zhuǎn)到springboot后相對來講配置相對較少，下面來講講springfox的介入（此插件遵循swagger規(guī)范）

pom插件引入

<pre>

  <!-- swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>

</pre>
具體版本可參考maven倉庫

SwaggerConfig

<pre>
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false);

}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("document api")
            .description("swagger style")
            .version("1.0.0")
            .build();
}

}
</pre>
注意的點@EnableSwagger2以及apiinfo（）里面的信息都是顯示在api文檔里面用來提醒用戶的。

最后具體的接口配置

@Api這個用來標記controller的內(nèi)部有description用來顯示整個controller的內(nèi)容
@ApiOperation 默認value屬性，提示這個接口的操作，可以寫入接口方法，數(shù)據(jù)，頭信息，具體可參考官方文檔
@ApiImplicitParam 添加在方法上可以提示參數(shù)的類型，說明，note屬性需添加
@ApiImplicitParams 由多個@ApiImplicitParam組成
@ApiResponse 接口返回信息提示需配置code，message，response等屬性
@ApiResonses 由多個@ApiResponse組成
@ApiParam 對單個參數(shù)進行注解
@ApiModule 配置需要說明的類型，需要寫value屬性才能正確顯示
@ApiModuleProperty 字段說明

總結(jié)

由于無法上傳圖片就不貼效果圖了，最后訪問swagger-ui.html就可以了
SpringMvc內(nèi)配置比較麻煩 需要用對資源進行攔截，要下載swagger的資源修改內(nèi)部的/v2/api-docs鏈接，相對較為麻煩，有興趣的同學(xué)也可以研究一下