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