SpringBoot整合Swagger3
本文将介绍下API可视化框架Swagger在SpringBoot框架中的整合流程,对Swagger3进行测试的一系列内容。
·
前言
本文将介绍下API可视化框架Swagger在SpringBoot框架中的整合流程,对Swagger3进行测试的一系列内容。
开发背景
若项目是使用前后端分离的方式来开发的,前后端代码的开发就需要开发员进行分工协作,以及进行前后端联调,开发时必须规范开发接口。接口文档的编写工作通常由后端开发员完成,接口文档中包含接口说明、请求URL、请求参数、请求方法、响应数据说明这五个部分。但手动编写接口文档是非常棘手的,所以,接下来我们可以使用Swagger来编写接口文档。
Swagger是什么?(官网)
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。Swagger是⼀个⽤于⽣成服务器接⼝的规范性⽂档、并且能够对接⼝进⾏测试的⼯具。
spring boot集成swagger3版本
-
引入pom.xml依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>
-
添加swagger3.0配置
package com.weh.config;
import com.google.common.collect.Sets;
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 springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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.Collections;
import java.util.List;
@Configuration
@EnableOpenApi //注意:这个注解是重点
public class SwaggerConfig {
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(" Api Doc")
.description("SpringFox 3.0.0 发布: https://www.xx.xx/swagger-ui/index.html")
.contact(new Contact("weh", null, "xxxxx"))
.version(
"Application Version: "
+ "1.0.0"
+ ", Spring Boot Version: "
+ SpringBootVersion.getVersion())
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.pathMapping("/")
// 定义是否开启swagger,false为关闭,可以通过变量控制
.enable(true)
// 将api的元信息设置为包含在json ResourceListing响应中。
.apiInfo(apiInfo())
// 接口调试地址
.host("http://localhost:9098")
// 选择哪些接口作为swagger的doc发布
.select()
// 关键部分:扫描包的路径
.apis(RequestHandlerSelectors.basePackage("com.weh.controller"))
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(Sets.newHashSet("http", "https"))
// 授权信息设置,必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());
}
/**
* 设置授权信息
*/
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());
}
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField =
FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List<InterceptorRegistration> registrations =
(List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
-
# 应用服务 WEB 访问端口 server: port: 9098
-
整体框架
访问网址:http://localhost:9098/doc.html
页面展示结果:
开放原子开发者工作坊旨在鼓励更多人参与开源活动,与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动,如meetup、训练营等,主打技术交流,干货满满,真诚地邀请各位开发者共同参与!
更多推荐
已为社区贡献1条内容
所有评论(0)