SpringBoot整合Swagger3的流程详解
作者：Splaying
这篇文章主要介绍了SpringBoot整合Swagger3的流程详解,Swagger最核心的类就是Docket、它可以配置作者信息、扫描类型,在SwaggerConfig配置类,添加@Configuration和@EnableOpenApi注解,需要的朋友可以参考下
1、创建项目
首先创建一个SpringBoot项目，随便勾选几个项目依赖，我选择了web、thymeleaf、lombok。
添加项目依赖，这里使用Swagger3（与Swagger2略有差异），并且添加一个好看一点的ui界面
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
2、配置Swagger
- Swagger最核心的类就是Docket、它可以配置作者信息、扫描类型…
- 首先创建一个SwaggerConfig配置类，添加@Configuration和@EnableOpenApi注解。
- 然后再向里面丢入Docket类的Bean实例，然后默认就可以访问了
@Configuration
@EnableOpenApi
public class SwaggerConfig {
@Bean
Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
}
}
访问localhost:8080/doc.html页面就可以看到了，/error接口的8种请求方式默认会出现在文档中，以及一些可以配置的信息
3、Swagger配置
上图红字的位置都是可以进行配置的，可以针对不同人写的不同接口等信息放在不同的分组中。
3.1、配置主页信息
其实这里有用的没几个，基本上很多信息都是默认给出。
@Bean
public ApiInfo apiInfo(){
return new ApiInfo("这是Swagger文档", //title名称
"归来仍是少年", //简介
"1.0", //版本
"urn:tos", //服务url
new Contact( //配置联系作者的方式
"xxx", //作者名称
"https://www.baidu.com", //连接
"xxxx@qq.com"), //作者邮箱
"Apache 2.0", //许可证
"http://www.apache.org/licenses/LICENSE-2.0", //许可证地址
new ArrayList<>()); //供应商的拓展
}
3.2、配置Docket信息
- 上面配置了主页面的一些信息，然后需要将这些信息注入到Docket中。
- 另外配置扫描接口的路径、过滤、分组以及是否开启等
- 当然这里可以拿到环境配置文件、可以根据不同的环境决定是否开启；一般情况下这些接口都是在开发环境中进行展示的，实际交付的时候是不会提供的。
- Docket是采用链式编程的形式进行配置，当存在多个Docket时可以通过不同的分组名称进行区分
@Bean
Docket docket_A(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("TestA");
}
@Bean
Docket docket_B (){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("TestB");
}
@Bean
Docket docket(Environment environment){
boolean result = environment.acceptsProfiles(Profiles.of("dev"));
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Splay") //默认分组Default改为Splay
.apiInfo(apiInfo()) //注入主页面信息
.enable(true) //是否启用swagger
.select() //扫描
/**
* apis指定要扫描的方式
* 1. basePackage(): 指定扫描的包
* 2. any(): 全部扫描
* 3. none(): 都不扫描
* 4. withClassAnnotation(): 通过类注解扫描
* 5. withMethodAnnotation(): 通过方法上的注解扫描
*/
.apis(RequestHandlerSelectors.basePackage("com.splay.controller"))
/**
* paths过滤不需要
* 1. ant(): 制定路径
* 2. none(): 全都不过滤
* 3. any(): 都过滤
* 4. regex(): 正则表达式
*/
//.paths(PathSelectors.ant("/splay/**")) //过滤不需要的路径
.build();
}
3.3、编写Controller
上面通过apis方法配置只扫描com.splay.controller包下的所有接口
@Controller
public class RouterController {
@GetMapping("/hello")
@ResponseBody
public String toHello(){
return "Hello Swagger";
}
}
这里可以绑定开启的环境，通过Environment拿到进行判断再决定是否开启。
3.4、效果图
4、注解的使用
- Swagger提供了很多的注解，几乎所有需要提供展示的东西都可以使用注解来开启。
- @Api配置Controller类、@ApiModel类可以给pojo进行展示、@ApiModelProperty配置pojo的属性、@ApiOperation配置方法…
4.1、pojo的配置
当返回值存在当前配置的pojo时，可以在model页面看到这些信息。
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户类" )
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
4.2、Controller的配置
Controller的名称将会展示为tags属性中的值
@Controller
@Api(tags = "路由控制类")
public class RouterController {
}
4.3、接口名称的配置
@PostMapping("/user")
@ResponseBody
@ApiOperation("返回用户信息") //接口名称、以及参数
public User sendUserMessage(@ApiParam("用户帐号") String username){
System.out.println(username);
return new User("admin", "123456");
}
4.4、效果图
到此这篇关于SpringBoot整合Swagger3的流程详解的文章就介绍到这了,更多相关SpringBoot整合Swagger3内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！