tips：后面还会为工程植入更多的组件，大家看完请帮忙三连~~谢谢大家，后续大家也可以将本工程保存为骨架工程使用。或者大家有什么想要看的组件集成也可以私信我，谢谢~~~
swagger文档目前应用也是很广泛的，本期为大家介绍spring-boot项目整合swagger文档
本着学习的心态我们整合比较新的swagger3，在实际项目中遇到的还是以swagger2为主。本期工程还是接上期整合完mybatis的工程。
swagger文档的整合大致分为三步
1.添加swagger的依赖
2.在yml配置文件中配置swagger所需的配置
3.添加swagger所需的config配置类
接下来我们一步一步来
1.添加依赖
swagger3的依赖如下
io.springfox springfox-boot-starter3.0.0
可以看出swagger3的依赖相对之前版本简化了很多
2.添加yml配置（我直接把所有配置贴出来，大家可以对比了看看）
server:
port: 8080
spring:
application:
name: demo
datasource:
username: root
url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf-8
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
mybatis:
mapper-locations: classpath:mybatis-mappers
@Component
@ConfigurationProperties("swagger")
@Data
public class SwaggerProperties {
private Boolean enable;
private String applicationName;
private String applicationVersion;
private String applicationDescription;
private String tryHost;
}
SwaggerConfiguration.class
package com.example.demo.config;
import io.swagger.models.auth.In;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.documentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.lang.reflect.Field;
import java.util.*;
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
private final SwaggerProperties swaggerProperties;
public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public Docket createRestApi() {
return new Docket(documentationType.OAS_30).pathMapping("/")
// 定义是否开启swagger，false为关闭，可以通过变量控制
.enable(swaggerProperties.getEnable())
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host(swaggerProperties.getTryHost())
// 选择哪些接口作为swagger的doc发布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
// 授权信息设置，必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
.description(swaggerProperties.getApplicationDescription())
.contact(new Contact("users", null, "734796109@qq.com"))
.version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
.build();
}
private List securitySchemes() {
ApiKey apiKey = new ApiKey("base_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
private List securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(new SecurityReference("base_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
.build()
);
}
@SafeVarargs
private final Set newHashSet(T... ts) {
if (ts.length > 0) {
return new linkedHashSet<>(Arrays.asList(ts));
}
return null;
}
@SuppressWarnings("unchecked")
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List registrations = (List) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**
@RequestMapping("/swagger-test")
@Api(tags = "swagger测试api")
public interface SwaggerApi {
@GetMapping("/swaggerTest")
@ApiOperation(value = "swagger文档测试接口", notes = "测试")
SwaggerApiResponse swaggerTest(SwaggerApiRequest request);
}
SwaggerAipController.class
package com.example.demo.controller;
import com.example.demo.api.SwaggerApi;
import com.example.demo.api.request.SwaggerApiRequest;
import com.example.demo.api.response.SwaggerApiResponse;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class SwaggerAipController implements SwaggerApi {
@Override
public SwaggerApiResponse swaggerTest(SwaggerApiRequest request) {
SwaggerApiResponse response = new SwaggerApiResponse();
response.setTest1("1");
response.setTest2("2");
response.setTest3("3");
return response;
}
}
完成之后启动项目，可以看到该接口再swagger上面的接口文档
填写参数，点击两个按钮就能测试接口
