【SpringBoot】7.SpringBoot整合Swagger

1. Swagger

简介：

• 一个 Api 框架
• RestFul Api 文档在线自动生成工具，Api 文档与 Api 定义同步更新
• 直接运行，可以在线测试 Api 接口
• 支持多种语言，如 java 、php 等

官网：https://swagger.io/

在项目中使用 Swagger 需要下面的依赖包

• springfox-boot-starter 3.0.0

2. SpringBoot 整合 Swagger

步骤：

1. 新建一个基于 SpringBoot 的 web 项目
2. 导入依赖
3. 编写 controller 层接口
4. 写一个配置类，配置 Swagger，并使用注解启动它
5. 测试运行

2.1 新建 SpringBoot 项目

环境信息：

• SpringBoot 2.7.3
• springfox-boot-starter 3.0.0
• IDEA
• Maven
• jdk 1.8

过程如下：

步骤1，新建一个 module

步骤2，修改包名和项目名

步骤3，选择一个 web 依赖就好

步骤4，写好 module 名称，然后点击完成

2.2 导入依赖

在 pom.xml 文件中，加入以下依赖信息

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        dependency>
1
2
3
4
5
6

整个 pom.xml 文件的依赖信息如下

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.7.3version>

    parent>
    <groupId>com.yuhuofeigroupId>
    <artifactId>springboot-swaggerartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <name>springboot-swaggername>
    <description>Swagger project for Spring Bootdescription>
    <properties>
        <java.version>1.8java.version>
    properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>

        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-boot-starterartifactId>
            <version>3.0.0version>
        dependency>

    dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
            plugin>
        plugins>
    build>

project>

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
38
39
40
41
42
43
44
45
46
47
48
49
50

2.3 编写 controller 层接口

写一个 LoginController.java 文件

package com.yuhuofei.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @Description
 * @ClassName LoginController
 * @Author yuhuofei
 * @Date 2022/8/21 21:29
 * @Version 1.0
 */
@RestController
@RequestMapping("/login")
public class LoginController {

    @GetMapping("/getToken")
    @ApiOperation("获取token")
    public String getToken() {
        String token = "这是一个简单的获取token的测试示例";
        return token;
    }

    @GetMapping("/getHello")
    @ApiOperation("获取hello")
    public String getHello() {
        return "Hello,World！";
    }

    @PostMapping("/login")
    @ApiOperation("登录接口")
    public String login(@ApiParam("用户名") @RequestParam("userName") String userName, @ApiParam("用户密码") @RequestParam("passWord") String passWord) {

        return "用户名是：" + userName + " 密码是：" + passWord;
    }
}
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

2.4 写配置类

编写 SwaggerConfig.java 配置类，配置展示信息

package com.yuhuofei.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

/**
 * @Description 开启Swagger
 * @ClassName SwaggerConfig
 * @Author yuhuofei
 * @Date 2022/8/21 21:34
 * @Version 1.0
 */
@Configuration
//开启swagger注解
@EnableOpenApi
public class SwaggerConfig{

    //配置Swagger的Docket的实例，Swagger页面展示的信息，都在此处配置；如果要配置多个分组，就创建多个Docket实例
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("Login")
                .select()
                //指定扫描的包或者注解
                .apis(RequestHandlerSelectors.basePackage("com.yuhuofei.controller").or(RequestHandlerSelectors.withClassAnnotation(RestController.class)))
                //过滤，只扫描带有下面请求路径的接口
//                .paths(PathSelectors.ant("/yuhuofei/**"))
                .build();
    }

    //配置Swagger的apiInfo
    private ApiInfo apiInfo() {

        Contact contact = new Contact("yuhuofei", "https://blog.csdn.net/Crezfikbd?type=blog", "xdssxxxxx.@qq.com");

        return new ApiInfo("yuhuofei的接口文档",
                "示例接口文档",
                "v1.0",
                "https:127.0.0.1",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );

    }

}

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

由于版本的问题，需要在 application.properties 中，加入以下的配置

server.port=8090
#解决swagger报错
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
1
2
3

2.5 测试运行

启动服务，在浏览器中请求 http://localhost:8090/swagger-ui/index.html，结果如下

使用 Swagger 测试一下接口，结果如下：

（1）测试 getHello 接口

（2）测试 login 接口