应项目组要求运用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>
重新打包,你会发现界面已经显示为中文。
本文是我写的第一遍随笔,谢谢大家的支持。