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

        <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

@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

访问地址： 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

/**
 * 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

如果是 SpringBoot 版本为 2.6 或是出现问题 Failed to start bean 'documentationPluginsBootstrapper'，请添加如下到 yaml

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

1
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

访问地址： 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

然后直接访问： http://localhost:8080/doc.html

配置类忽略

# 参考链接

编辑

上次更新: 2023/11/28, 12:55:10

← Flyway 数据库版本管理实战指南 MP 配置分页→