1. New project

First of all, let's simply build a simple SpringBoot project. If you haven't created a SpringBoot project before, you can refer to an article I wrote before to create a SpringBoot project: Using IDEA to create a SpringBoot project
insert image description here

2. Import dependencies

We need to use Swagger3 and need to import the corresponding dependencies, because Swagger3 currently only has one version, so there is no need to choose the version, just use the version 3.0.0

<?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.6</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.lijinjiang</groupId>
    <artifactId>SpringBootSwagger</artifactId>
    <version>1.0.0</version>
    <name>SpringBootSwagger</name>
    <description>SpringBootSwagger</description>

    <properties>
        <!-- JDK 版本 -->
        <java.version>1.8</java.version>
        <!-- Lombok 版本 -->
        <lombok.version>1.18.24</lombok.version>
        <!-- Swagger 版本 -->
        <swagger.version>3.0.0</swagger.version>
    </properties>

    <dependencies>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${
    
    lombok.version}</version>
            <scope>provided</scope>
        </dependency>
        <!--Swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${
    
    swagger.version}</version>
        </dependency>

        <!-- 配置元数据 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

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

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.7.6</version>
            </plugin>
        </plugins>
    </build>

</project>

3.yml configuration

We change the suffix name of application.properties to yml, and create a corresponding test environment: application-test.yml, and complete the configuration information in it. Here we configure the configuration information of Swagger into application-test.yml, if If the SpringBoot version used is greater than or equal to 2.6.0, you need to configure path matching rules, otherwise an error will be reported

application.yml

# Tomcat配置
server:
  # 端口
  port: 8080

# Spring配置
spring:
  application:
    # 应用名称
    name: SpringBootSwagger
  # 配置文件
  profiles:
    # 运行环境
    active: test
  # 路径匹配机制
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

application-test.yml

# Document配置信息
swagger:
  # 文档标题
  title: SpringBoot整合Swagger案例
  # 组织信息
  group-name: SpringBoot-Swagger
  # 是否开启
  enable: true
  # 描述信息
  describe: 测试API接口平台
  # 版本信息
  version: Release 1.0.0
  # 扫包路径
  scan-package: com.lijinjiang.swagger.controller
  # 组织信息
  terms-of-service-url: https://gitee.com/lijinjiang01
  # 联系人作者
  contact-name: 李晋江
  # 链接
  contact-url: https://lijinjiang.blog.csdn.net
  # 邮箱
  contact-email: lijinjiang01@126.com

4. Swagger configuration class

Create a new com.lijinjiang.swagger.config.property package in the java directory, and create the corresponding Swagger property configuration entity class SwaggerProperty

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

/**
 * @Description Swagger接口文档配置类
 * @Author 03010430
 * @ModifyDate 2023/2/13 14:36
 */
@Data
@ConfigurationProperties("swagger")
public class SwaggerProperty {
    
    
    //系统标题
    private String title;
    //分组名称
    private String groupName;
    //是否开启
    private Boolean enable = true;
    //描述信息
    private String describe;
    //版本信息
    private String version;
    //扫描路径
    private String scanPackage;
    //组织链接
    private String termsOfServiceUrl;
    //联系人名称
    private String contactName;
    //联系人url
    private String contactUrl;
    //联系人email
    private String contactEmail;
}

Create the Swagger configuration class SwaggerConfig under the com.lijinjiang.swagger.config package

import com.lijinjiang.swagger.config.property.SwaggerProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import javax.annotation.Resource;
import java.sql.Timestamp;
import java.util.Date;

/**
 * @Description Swagger配置文件
 * @Author 03010430
 * @ModifyDate 2023/2/13 14:35
 */
@Configuration
@EnableConfigurationProperties(SwaggerProperty.class)
public class SwaggerConfig {
    
    

    @Resource
    private SwaggerProperty swaggerProperty;

    @Bean
    public Docket createApiDoc() {
    
    
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName(swaggerProperty.getGroupName())
                .enable(swaggerProperty.getEnable())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperty.getScanPackage()))
                .build().directModelSubstitute(Timestamp.class, Date.class);
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title(swaggerProperty.getTitle())
                .description(swaggerProperty.getDescribe())
                .version(swaggerProperty.getVersion())
                .termsOfServiceUrl(swaggerProperty.getTermsOfServiceUrl())
                .contact(new Contact(swaggerProperty.getContactName(), swaggerProperty.getContactUrl()
                        , swaggerProperty.getContactEmail()))
                .build();
    }
}

5. Simulation case

Here we simulate the addition, deletion, modification, and query operations of a user class.
First create a com.lijinjiang.swagger.entity package, and then create the corresponding user class User

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;
import java.sql.Timestamp;

/**
 * @Description 用户类
 * @Author 03010430
 * @ModifyDate 2023/2/13 14:52
 */
@Data
@ApiModel(description = "用户类")
public class User implements Serializable {
    
    
    private static final long serialVersionUID = 1L;
    @ApiModelProperty(value="主键ID")
    private String id;
    @ApiModelProperty(value="账号")
    private String account;
    @ApiModelProperty(value="密码")
    private String password;
    @ApiModelProperty(value="头像")
    private String avatar;
    @ApiModelProperty(value="电话")
    private String phone;
    @ApiModelProperty(value="创建时间")
    private Timestamp ctime;
}

Then create the com.lijinjiang.swagger.controller package, and create the user control class UserController , and simulate the user's addition, deletion, modification and query operations in it (the specific Mapper and Service are not written)

import com.lijinjiang.swagger.common.Result;
import com.lijinjiang.swagger.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * @Description 用户控制器
 * @Author 03010430
 * @ModifyDate 2023/2/13 14:56
 */
@Api(tags = {
    
    "用户管理"})
@RestController
public class UserController {
    
    

    @ApiOperation(value = "新增用户", notes = "根据传入的数据，新增用户", produces = "application/json")
    @PostMapping("/users")
    public Result addUser(@RequestBody User user) {
    
    
        //具体业务代码
        return Result.success(null);
    }

    @ApiOperation(value = "删除用户", notes = "根据传入的id，删除对应用户")
    @DeleteMapping("/users/{id}")
    public Result deleteUser(@PathVariable("id") String id) {
    
    
        //具体业务代码
        return Result.success(null);
    }

    @ApiOperation(value = "修改用户", notes = "根据传入的数据，修改用户")
    @PutMapping("/users")
    public Result updateUser(@RequestBody User user) {
    
    
        //具体业务代码
        return Result.success(null);
    }

    @ApiOperation(value = "查询用户", notes = "根据传入的id，查找返回对应用户信息")
    @GetMapping("/users/{id}")
    public Result queryUser(@PathVariable("id") String id) {
    
    
        //具体业务代码
        return Result.success(null);
    }
}

6. Project running

Run the project startup class (here I changed the startup class name to Application) Application , and then log in to the UI interface of Swagger
http://localhost:8080/swagger-ui/index.html

insert image description here

You can also do some simple tests here, but the operation and display are not very friendly, it is better to introduce other display UI

7. Introduce knife4j

Because the default UI display of Swagger is not very friendly, according to the choices of everyone in the market, I finally choose knife4j as the display UI of Swagger
here to adjust the pom.xml, and directly change the imported Swagger dependency to introduce knife4j.

<!-- Knife4j 版本 -->
<knife4j.version>3.0.3</knife4j.version>

<!-- Knife4j 接口文档 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

Add knife4j to application-test.yml to enable enhancements

# knife4j配置
knife4j:
  # 开启增强配置
  enable: true

insert image description here
After using it for a period of time, I found that it is more convenient to view documents and test interfaces on this system. Of course, if you use postman to test, you can directly import the url link of the above Swagger interface into postman, and you can also test

8. Project structure

Here is the final structure tree of the project for your reference