應項目組要求運用swagger技術管理項目接口文檔，由于項目運用的springBoot開發，所以這里我說一下swagger的一些相關配置和需要注意的地方。下邊先說一下使用swagger2之前做的一些步驟。
第一步，引入swagger相關jar的pom。為了便于大家直接拷貝這里沒有插入圖片（此處應有贊贊！！！），大家可以直接copy。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
第二步，配置項目運行的bean，這里可能大家不懂了（可以看一下springBoot相關的知識點），總結網上的一些資料，主要有兩種的配置方式，區別在于掃描包的單與多，即是否支持多包掃描的配置。下邊分別說明。
A、單路勁掃描配置，抒寫swagger2類。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.luckin.ai.backend.ui.controller"))//單路徑掃描
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("項目接口文檔")//項目描述1
.description("簡單優雅的restfun風格")//項目描述2
.termsOfServiceUrl("http://blog.csdn.net/saytime")//項目描述3
.version("1.0")
.build();
}
}
B、多路徑掃描（抒寫Swagger2UIConfig類）
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2UIConfig {
? ? @Bean
? ? public Docket createRestApi() {
? ? ? ? return new Docket(DocumentationType.SWAGGER_2)
? ? ? ? .apiInfo(apiInfo())
? ? ? ? .select()
? ? ? ? ? ? ? ? .apis(Swagger2UIConfig.basePackage("com.luckin.ai.backend.ui.controller,com.luckin.ai.report.controller"))//多路徑掃描，之間用逗號分隔
? ? ? ? ? ? ? ? .paths(PathSelectors.any()).build();
? ? }
? ? public static Predicate<RequestHandler> basePackage(final String basePackage) {
? ? ? ? return new Predicate<RequestHandler>() {
? ? ? ? ? ? @Override
? ? ? ? ? ? public boolean apply(RequestHandler input) {
? ? ? ? ? ? ? ? return declaringClass(input).transform(handlerPackage(basePackage)).or(true);
? ? ? ? ? ? }
? ? ? ? };
? ? }
? ? private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
? ? ? ? return new Function<Class<?>, Boolean>() {
? ? ? ? ? ? @Override
? ? ? ? ? ? public Boolean apply(Class<?> input) {
? ? ? ? ? ? ? ? for (String strPackage : basePackage.split(",")) {
? ? ? ? ? ? ? ? ? ? boolean isMatch = input.getPackage().getName().startsWith(strPackage);
? ? ? ? ? ? ? ? ? ? if (isMatch) {
? ? ? ? ? ? ? ? ? ? ? ? return true;
? ? ? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? ? }
? ? ? ? ? ? ? ? return false;
? ? ? ? ? ? }
? ? ? ? };
? ? }
? ? /**
? ? * @param input RequestHandler
? ? * @return Optional
? ? */
? ? private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
? ? ? ? return Optional.fromNullable(input.declaringClass());
? ? }
? ? @Bean
? ? public ApiInfo apiInfo() {
? ? ? ? return new ApiInfoBuilder()
? ? ? ? .title("智能平臺接口文檔")
.description("")
? ? ? ? ? ? .version("1.0")
? ? ? ? ? ? .build();
? ? }
}
如上兩種配置都可以，區別便是可以多路徑掃描，路徑之間用逗號分隔。
第三步，抒寫接口配置注釋，這樣項目才能掃描到需要展示的接口api來生成文檔。下邊介紹一下用到的注釋。
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：一個請求參數
@ApiImplicitParams：多個請求參數
因為網上有關swagger接口注釋示例很多，這里就不再給大家廢話了，主要說明一下大概會遇到的幾種方式下邊是給大家的一下示例：
上邊需要注意的地方是dataType需要對應，大家可能想問paramType是什么，這里說明以下這個坑。paramType的參數有以下幾種方式：
header：請求參數放置于Request Header，使用@RequestHeader獲取
query：請求參數放置于請求地址，使用@RequestParam獲取
path：（用于restful接口）-->請求參數的獲取：@PathVariable
body（一般不用）
form（一般不用）
注意：這個paramType必須對應才能在最后展示的接口文檔界面發送請求。
第四步，可以啟動項目了，啟動以后訪問地址：http://your ip:your 端口/swagger-ui.html，配置沒問題的話會展示如下界面：
需要等待幾秒鐘，正在掃描需要生成文檔的配置。
走到這里，大家可能會發現我的界面怎么是英文的尼，接下來給大家說一下swagger的漢化操作。
首先找到剛開始引入pom的jar
找到這個jar包修改swagger-ui.hmtl中加入js引用：
<!--國際化操作：選擇中文版 -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
重新打包，你會發現界面已經顯示為中文。
本文是我寫的第一遍隨筆，謝謝大家的支持。
