言成言成啊 | Kit Chen's Blog

Swagger

一、前后端分离

一开始的网站,前端只需要管理静态页面,后端通过模板引擎比如jsp来渲染数据。

前后端分离,目前最主流的技术栈是Vue+SpringBoot

前端:控制层、视图层

  • 前端工程化:伪造后端数据,如json。也就是说不需要后端,前端工程依旧能跑起来。

后端:控制层、服务层、数据访问层

前后端分离优点

  1. 相对独立、低耦合,仅通过API进行交互
  2. 前后端可以部署在不同服务器

前后端分离问题

  1. 前后端集成联调,前端开发和后端开发无法做到及时协商,尽早解决,最终会导致问题集中。

解决方案

  1. 制定schema计划,实时更新最新API,降低集成风险
  2. 前后端未分离时,word文档
  3. 前后端分离,需要前端测试接口,后端提供接口,这就需要Swagger了。

二、Springboot集成Swagger

swagger号称世界上最流行的api框架,RestFul Api文档在线自动生成工具,api文档与api定义同步更新,并且可以在线测试接口,支持多种语言。

swagger3.0参考文章

项目中使用Swagger需要springbox的jar包,里面包含

  1. swagger2
  2. ui

Springboot集成Swagger步骤

  1. 新建springboot-web项目
  2. 导入依赖
  3. 配置swagger

SpringBoot引用swagger3只需要导入以下

1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>

SwaggerConfig

1
2
3
@Configuration
public class SwaggerConfig {
}

HaloSwagger

1
2
3
4
5
6
7
@RestController
public class HaloSwagger {
@GetMapping("/halo")
public String halo(){
return "halo wode";
}
}

访问http://localhost:8080/swagger-ui/index.html

三、配置Swagger信息

也很简单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
@Configuration
public class SwaggerConfig {
//配置swagger的实例
@Bean
public Docket docket(Environment environment) {
Profiles profiles=Profiles.of("dev");
//获取项目环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
/**
* apis():配置扫描的包,基本包、any、none
*/
.apis(RequestHandlerSelectors.basePackage("top.meethigher.swagger.controller"))
/**
* 过滤路径
*/
.paths(PathSelectors.ant("/controller/**"))
.build();
}

//配置swagger信息
private ApiInfo apiInfo() {
return new ApiInfo(
"Swagger Api文档",
"代码改变世界!",
"1.0",
"https://localhost:8080/swagger-ui/index.html",
new Contact("meethigher", "https://meethigher.top", "meethigher@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
}

application.properties

1
spring.profiles.active=dev

application-dev.yml

1
2
server:
port: 8080

application-prod.yml

1
2
server:
port: 8080

四、分组

配置多个Docket即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@Configuration
public class SwaggerConfig {
//配置swagger的实例
@Bean
public Docket docket1(Environment environment) {
Profiles profiles=Profiles.of("dev");
//获取项目环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("呵呵")
.enable(flag);
}
//配置swagger的实例
@Bean
public Docket docket(Environment environment) {
Profiles profiles=Profiles.of("dev");
//获取项目环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("哈哈")
.enable(flag);
}

//配置swagger信息
private ApiInfo apiInfo() {
return new ApiInfo(
"Swagger Api文档",
"代码改变世界!",
"1.0",
"https://localhost:8080/swagger-ui/index.html",
new Contact("meethigher", "https://meethigher.top", "meethigher@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
}

五、实体类配置

@Api:修饰整个类,描述Controller的作用

@ApiOperation:描述一个类的一个方法,或者说一个接口

@ApiModel:用对象来接收参数 ,修饰类

@ApiModelProperty:用对象接收参数时,描述对象的一个字段

@NotBlank/@NotNull:字段不能为空

@ApiResponse:HTTP响应其中1个描述

@ApiResponses:HTTP响应整体描述,一般描述错误的响应

@ApiIgnore:使用该注解忽略这个API

@ApiError :发生错误返回的信息

@ApiParam:单个参数描述

@ApiImplicitParam:一个请求参数,用在方法上

@ApiImplicitParams:多个请求参数

发布:2021-04-26 00:38:47
修改:2021-05-27 00:35:43
链接:https://meethigher.top/blog/2021/swagger/
标签:spring 
付款码 打赏 分享