Swagger 3.0框架搭建及简单示例
Posted Elon.Yang
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Swagger 3.0框架搭建及简单示例相关的知识,希望对你有一定的参考价值。
在基于Spring boot搭建的Java微服务上集成Swagger 3.0方便Restful接口调测。由于第三方组件升级和业务连续性原因,原来的Swagger 2.0需要升级到Swagger 3.0。
一. 引入Swagger 3.0依赖的包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>org.springframework.plugin</groupId>
<artifactId>spring-plugin-core</artifactId>
<version>2.0.0.RELEASE</version>
</dependency>
二、增加Swagger配置初始化代码
import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ExampleBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableOpenApi
public class Swagger3Config
@Bean
public Docket api()
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
.apiInfo(getApiInfo())
.globalRequestParameters(buildGlobalHeaderParam());
private ApiInfo getApiInfo()
ApiInfo apiInfo = new ApiInfoBuilder().title("Swagger 3.0")
.description("Swagger 3.0配置Demo")
.termsOfServiceUrl("https://blog.csdn.net/ylforever")
.version("1.0")
.build();
return apiInfo;
/**
* 构建公共参数
*
* @return elon
*/
private List<RequestParameter> buildGlobalHeaderParam()
List<RequestParameter> globalParamList = new ArrayList<>();
RequestParameter account = new RequestParameterBuilder().name("account")
.in(ParameterType.HEADER)
.example(new ExampleBuilder().value("zh1234").build())
.build();
globalParamList.add(account);
RequestParameter name = new RequestParameterBuilder().name("name")
.in(ParameterType.HEADER)
.example(new ExampleBuilder().value("zhang san").build())
.build();
globalParamList.add(name);
return globalParamList;
(1)使用注解扫描API,代替指定controller文件路径的方式更加灵活。也更方便抽取成公共组件。
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
(2)初始化公共参数。项目中有约定大部分接口调用时都需要传递的参数,在初始化时统一设定。
.globalRequestParameters(buildGlobalHeaderParam());
说明:在初始化全局公共参数的代码中指定了默认值,但是没有生效(在Swagger 2.0中是可以的)。这好像是Swagger 3.0的一个问题,大家如知道怎样设置默认参数的话,望不吝赐教。这个不影响使用,只是每次用的时候都需要手工输入参数。
.example(new ExampleBuilder().value("zh1234").build())
三. 简单样例代码
(1). controller接口代码
import javax.servlet.http.HttpServletRequest;
@RestController
@RequestMapping("/v1/swagger3")
@Api(tags = "Swagger3.0测试服务")
public class Swagger3Controller
private static final Logger LOGGER = LogManager.getLogger(Swagger3Controller.class);
@PostMapping("/metod")
@ApiOperation(value = "Swagger3.0测试接口")
public String swagger3Method(@RequestBody String body)
HttpServletRequest request = ((ServletRequestAttributes)RequestContextHolder.getRequestAttributes())
.getRequest();
String account = request.getHeader("account");
String name = request.getHeader("name");
LOGGER.info("account:|name:", account, name);
return body;
(2)swagger访问页面
注意:Swagger2.0升级到Swagger3.0后访问地址有变化。后缀由swagger-ui.html改为swagger-ui/index.html
样例代码github地址: https://github.com/ylforever/elon-swagger3
以上是关于Swagger 3.0框架搭建及简单示例的主要内容,如果未能解决你的问题,请参考以下文章
搭建基础后台框架及整合Swagger2及整合mybatisPlus代码器
net6 项目搭建及引用框架记录(log4net,autofac,exception,api result,jwt,efcore)一建立项目,使用Swagger
net6 项目搭建及引用框架记录(log4net,autofac,exception,api result,jwt,efcore)一建立项目,使用Swagger
net6 项目搭建及引用框架记录(log4net,autofac,exception,api result,jwt,efcore)一建立项目,使用Swagger