【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 文件中，加入以下依赖信息

        <!--swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

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

<?xml version="1.0" encoding="UTF-8"?>
<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.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.3</version>

    </parent>
    <groupId>com.yuhuofei</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-swagger</name>
    <description>Swagger project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!--swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

    </dependencies>

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

</project>

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;
    }
}

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<>()
        );

    }

}

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

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

2.5 测试运行

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

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

（1）测试 getHello 接口

（2）测试 login 接口