最近项目需要提供api文档给测试及需求,网上文章很多,其实挺简单的。但是注解不是很适合我,所以我又整理了一版。
其中代码参考了很多网上的文章,但是也找不到具体的链接了。我只是做了整合和备注。如果有需要,可以私聊我加上出处。谢谢理解
直接上代码,看注解1、2、3、4基本就可以直接运行起来。
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.RequestHandlerSelectors.basePackage;
/**
* Swagger 是一个规范和完整的框架,
* 用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
* 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
* 文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
*
* swagger集成:
* 1.pom.xml导包
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- http://localhost:8080/swagger-ui.html UI展示 http://localhost:8080/v2/api-docs 无UI的描述API的swagger元数据json https://editor.swagger.io/ -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- http://localhost:8080/doc.html 国人开发的增强UI<https://www.xiaominfo.com/> -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
*
* 2.SwaggerConfig.java
@ EnableSwagger2支持Swagger 2的SpringFox支持。
DocumentationType.SWAGGER_2告诉Docket bean我们正在使用Swagger规范的版本2。
select()创建一个构建器,用于定义哪些控制器及其生成的文档中应包含哪些方法。
apis()定义要包含的类(控制器和模型类)。这里我们包括所有这些,但您可以通过基础包,类注释等来限制它们。
paths()允许您根据路径映射定义应包含哪个控制器的方法。我们现在包括所有这些,但您可以使用正则表达式等限制它。
*
* 3.Controller加注解
* 常用注解:
3.1类名级别:
@Api(value = "用户相关", tags = "用户相关")
或者
@ApiIgnore//swagger页面不扫描此Controller
3.2方法级别
@ApiOperation(value = "获取群组的用户", notes = "获取群组的用户notes")
@ApiImplicitParams({
@ApiImplicitParam(name = "chatId", value = "userId/groupId", required = true, paramType = "query"),
@ApiImplicitParam(name = "loginAid", value = "登录用户Id", required = true, paramType = "query", dataType = "String")
})
* 4.Vo加注解
@ApiModelProperty(value = "手机号", example = "13000000000", required = true)
private String mobile;
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//配置文件添加是否允许展示swagger页面,上线时一定要改为false
@Value("${swagger.show}")
private boolean flag;
// 定义分隔符
private static final String splitor = ";";
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.enable(flag)
.apiInfo(apiInfo())
.select()
//.apis(RequestHandlerSelectors.any()) //扫描所有包
//.apis(basePackage("com.guoyin.im.controller.im"+splitor+"com.guoyin.im.controller.system")) //自定义扫描
.apis(basePackage("com.guoyin.im.controller.im")) //自定义扫描
.paths(PathSelectors.any())
.build()
//.globalOperationParameters(globalOperation()); //每个接口调用都填写token
.securitySchemes(security()); //统一填写一次token
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("TQ项目API接口")
.description("This is a restful api document of TQ")
.version("1.0.0")
.build();
}
//给每个方法添加固定参数
private List<Parameter> globalOperation(){
// 添加请求参数,我们这里把access_token作为请求头部参数传入后端
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
/**
* paramType:表示参数放在哪个地方
* header-->请求参数的获取:@RequestHeader(代码中接收注解)
* query-->请求参数的获取:@RequestParam(代码中接收注解)
* path(用于restful接口)-->请求参数的获取:@PathVariable(代码中接收注解)
* body-->请求参数的获取:@RequestBody(代码中接收注解)
* form(不常用)
*/
parameterBuilder.name("access_token").description("token")
.modelRef(new ModelRef("string")).parameterType("query").required(false).build();
parameters.add(parameterBuilder.build());
return parameters;
}
//所有方法统一传递固定参数
private List<ApiKey> security() {
return newArrayList(
new ApiKey("token", "access_token", "query")
);
}
//自定义扫描多个路径
public static Predicate<RequestHandler> basePackage(final String basePackage) {
return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
}
//自定义扫描多个路径
private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
return input -> {
// 循环判断匹配
for (String strPackage : basePackage.split(splitor)) {
boolean isMatch = input.getPackage().getName().startsWith(strPackage);
if (isMatch) {
return true;
}
}
return false;
};
}
//自定义扫描多个路径
private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
return Optional.fromNullable(input.declaringClass());
}
}