Swagger 2 和 3 安装区别
# 前言
官方首页:API Documentation & Design Tools for Teams | Swagger (opens new window)
# 2
swagger 2 文档地址:OpenAPI Specification - Version 2.0 | Swagger (opens new window)
其中 SpringBoot 版本不可过高
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.5.6</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
1
2
3
4
5
6
2
3
4
5
6
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
/**
* 配置 Swagger 2
* 注册一个 Bean 属性
* enable():是否启用 Swagger,启用后才能在浏览器中进行访问
* groupName():用于配置 API 文档的分组
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(true)
.groupName("v1")
.select()
// 过滤路径
//.paths(PathSelectors.ant())
// 指定扫描的包
.apis(RequestHandlerSelectors.basePackage("com.example.compkeylab.controller"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("电商实验")
.description("测试接口文档")
//.termsOfServiceUrl("SSS")
//.contact(new Contact("SSS", "SSS", "SSS")) .version("Apache 2.0")
.build();
}
}
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
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
访问地址: http://localhost:8080/swagger-ui.html
# 3
swagger 3 文档地址:OpenAPI Specification - Version 3.0.3 | Swagger (opens new window)
导入 swagger 3 有两种方式:SpringFox 工具(旧),SpringDoc 工具(新)
# SpringFox
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
1
2
3
4
5
2
3
4
5
/**
* swagger3 配置
*/
@Configuration
public class Swagger3Configuration {
Boolean swaggerEnabled = true;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 是否开启
.enable(swaggerEnabled)//true
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.compkeylab"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("电商实验")
//创建人
.contact(new Contact("sss", "http://www.baidu.com", "sss@x.com"))
.version("1.0")
.description("描述信息")
.build();
}
}
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
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
如果是 SpringBoot 版本为 2.6 或是出现问题 Failed to start bean 'documentationPluginsBootstrapper'
,请添加如下到 yaml
spring:
mvc:
pathmatch:
matching-strategy: ANT_PATH_MATCHER
1
2
3
4
2
3
4
还有就是如果 swagger 3 移除 swagger 2 中自带的 guava 依赖,如果您的项目中使用了 guava,那么在迁移 swagger 3 之后需要导入 guava 依赖
<!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>28.0-jre</version>
</dependency>
1
2
3
4
5
6
2
3
4
5
6
访问地址: http://localhost:8080/swagger-ui/index.html
# SpringDoc
暂时不使用
# knife4j
使用 knife4j 优化接口文档
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
1
2
3
4
5
2
3
4
5
然后直接访问: http://localhost:8080/doc.html
配置类忽略
# 参考链接
编辑 (opens new window)
上次更新: 2023/11/28, 12:55:10