應(yīng)項(xiàng)目組要求運(yùn)用swagger技術(shù)管理項(xiàng)目接口文檔，由于項(xiàng)目運(yùn)用的springBoot開(kāi)發(fā)闷祥，所以這里我說(shuō)一下swagger的一些相關(guān)配置和需要注意的地方娱颊。下邊先說(shuō)一下使用swagger2之前做的一些步驟。
第一步凯砍，引入swagger相關(guān)jar的pom箱硕。為了便于大家直接拷貝這里沒(méi)有插入圖片（此處應(yīng)有贊贊！Ｎ蝰谩＞缯帧），大家可以直接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>
第二步惠昔，配置項(xiàng)目運(yùn)行的bean，這里可能大家不懂了（可以看一下springBoot相關(guān)的知識(shí)點(diǎn)）挑势，總結(jié)網(wǎng)上的一些資料镇防，主要有兩種的配置方式，區(qū)別在于掃描包的單與多潮饱，即是否支持多包掃描的配置来氧。下邊分別說(shuō)明。
A、單路勁掃描配置啦扬，抒寫(xiě)swagger2類(lèi)中狂。
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("項(xiàng)目接口文檔")//項(xiàng)目描述1
.description("簡(jiǎn)單優(yōu)雅的restfun風(fēng)格")//項(xiàng)目描述2
.termsOfServiceUrl("http://blog.csdn.net/saytime")//項(xiàng)目描述3
.version("1.0")
.build();
}
}
B、多路徑掃描（抒寫(xiě)Swagger2UIConfig類(lèi)）
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"))//多路徑掃描扑毡，之間用逗號(hào)分隔
? ? ? ? ? ? ? ? .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("智能平臺(tái)接口文檔")
.description("")
? ? ? ? ? ? .version("1.0")
? ? ? ? ? ? .build();
? ? }
}
如上兩種配置都可以胃榕，區(qū)別便是可以多路徑掃描，路徑之間用逗號(hào)分隔瞄摊。
第三步勤晚，抒寫(xiě)接口配置注釋?zhuān)@樣項(xiàng)目才能掃描到需要展示的接口api來(lái)生成文檔。下邊介紹一下用到的注釋泉褐。
@Api：修飾整個(gè)類(lèi)赐写，描述Controller的作用
@ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)膜赃，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
@ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
因?yàn)榫W(wǎng)上有關(guān)swagger接口注釋示例很多挺邀，這里就不再給大家廢話了，主要說(shuō)明一下大概會(huì)遇到的幾種方式下邊是給大家的一下示例：
上邊需要注意的地方是dataType需要對(duì)應(yīng)跳座，大家可能想問(wèn)paramType是什么端铛，這里說(shuō)明以下這個(gè)坑。paramType的參數(shù)有以下幾種方式：
header：請(qǐng)求參數(shù)放置于Request Header疲眷，使用@RequestHeader獲取
query：請(qǐng)求參數(shù)放置于請(qǐng)求地址禾蚕，使用@RequestParam獲取
path：（用于restful接口）-->請(qǐng)求參數(shù)的獲取：@PathVariable
body（一般不用）
form（一般不用）
注意：這個(gè)paramType必須對(duì)應(yīng)才能在最后展示的接口文檔界面發(fā)送請(qǐng)求狂丝。
第四步换淆，可以啟動(dòng)項(xiàng)目了，啟動(dòng)以后訪問(wèn)地址：http://your ip:your 端口/swagger-ui.html几颜，配置沒(méi)問(wèn)題的話會(huì)展示如下界面：
需要等待幾秒鐘倍试，正在掃描需要生成文檔的配置。
走到這里蛋哭，大家可能會(huì)發(fā)現(xiàn)我的界面怎么是英文的尼县习，接下來(lái)給大家說(shuō)一下swagger的漢化操作。
首先找到剛開(kāi)始引入pom的jar
找到這個(gè)jar包修改swagger-ui.hmtl中加入js引用：
<!--國(guó)際化操作：選擇中文版 -->
<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>
重新打包谆趾，你會(huì)發(fā)現(xiàn)界面已經(jīng)顯示為中文躁愿。
本文是我寫(xiě)的第一遍隨筆，謝謝大家的支持沪蓬。
