---

Swagger 教程(笔记) Knife4j

原创 已于 2025-09-23 15:18:44 修改 · 粉丝可见 · 1.8k 阅读 · 25 · 21 GEO检测 · 编辑
文章链接：https://blog.csdn.net/hacker_51/article/details/142533153

目录

[TOC]

目录

[TOC]

MySQLuser 表

DROP DATABASE if EXISTS study;
CREATE DATABASE study;
USE study;
CREATE TABLE `users` (
	`id` INT(10) NOT NULL AUTO_INCREMENT,
	`username` VARCHAR(255) NOT NULL COLLATE 'utf8_general_ci',
	`password` VARCHAR(255) NOT NULL COLLATE 'utf8_general_ci',
	`create_time` DATETIME NOT NULL,
	`update_time` DATETIME NOT NULL,
	PRIMARY KEY (`id`) USING BTREE
)
COLLATE='utf8_general_ci'
ENGINE=InnoDB
;
INSERT INTO `users`(`username`,`password`,`create_time`,`update_time`) VALUES("Angindem","abc123456","2024-9-25 22:02:15","2024-9-25 22:02:15");

application.properties

# Mybatis 查找 *mapper.xml 路径
mybatis.mapper-locations=classpath:mappers/*xml
# MyBatis 为该包下的所有类自动注册别名。
mybatis.type-aliases-package=com.angindem.mybatis.po 

server.port=8080

# Mysql 数据库配置
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url= jdbc:mysql://localhost:3306/study
spring.datasource.username= root
spring.datasource.password= 123456

# 开启驼峰命名映射
mybatis.configuration.map-underscore-to-camel-case=true

# 打印 SQL 语句
mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

UserController

package com.angindem.controller;

import com.angindem.po.User;
import com.angindem.service.IUserService;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {

    private final IUserService userService;

    @GetMapping("/list")
    public List<User> getUserList(User user){
        return userService.getUserList(user);
    }

    @GetMapping("/id")
    @ApiOperation(value = "获取用户接口",notes = "根据 id 和 用户名 参数查询用户")
    public List<User> getUserByIdOrUserName(Integer id,String name){
        return userService.getUserByIdOrUserName(id,name);
    }
}

userMapper

package com.angindem.mapper;

import com.angindem.po.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;

import java.util.List;

@Mapper
public interface UserMapper {

    @Select("select * from users")
    List<User> queryByUser(User user);
    @Select("select * from users where id = #{id} or username = #{name}")
    List<User> getUserByIdOrUserName(Integer id, String name);
}

User

package com.angindem.po;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    private Integer id;
    private String username;
    private String password;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
}

UserServiceImpl

package com.angindem.service.impl;

import com.angindem.mapper.UserMapper;
import com.angindem.po.User;
import com.angindem.service.IUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserServiceImpl implements IUserService {

    @Autowired
    private UserMapper userMapper;

    @Override
    public List<User> getUserList(User user) {
        return userMapper.queryByUser(user);
    }

    @Override
    public List<User> getUserByIdOrUserName(Integer id, String name) {
        return userMapper.getUserByIdOrUserName(id,name);
    }
}

IUserService

package com.angindem.service;

import com.angindem.po.User;

import java.util.List;


public interface IUserService {
    List<User> getUserList(User user);

    List<User> getUserByIdOrUserName(Integer id, String name);
}

Swagger教程

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接文档，以及在线接口调试页面。 官网: https://swagger.io/

对于使用Swagger插件，目前，一般都使用knife4j框架。如果直接使用官网 Swagger ，配置一些都是比较麻烦的。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。

Swagger前置配置

第一步：引入依赖，导入Maven坐标

<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>3.0.2</version>
</dependency>

第二步：webConfig配置类中加入 knife4j相关配置

@Bean
   public Docket docket(){

       // API 接口文档主体信息的创建
       ApiInfo apiInfo = new ApiInfoBuilder()
               .title("Angindem项目接口文档")    // 项目的标题
               .version("1.0")
               .contact(new Contact("Angindem","http://www.xxxxx.com/","xxxxxxxx@qq.com")) // 添加作者个人信息
               .termsOfServiceUrl("http://www.xxx.com/")   // 服务的网址，公司或者个人的访问网址
               .description("这个项目可以使我们更加了解 Swagger ")  // 项目的描述
               .build();   // 注意 记得 build 创建

       // API 接口文档的 接口信息内容的创建
       Docket docket = new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo)   // 放入主体信息
               .select()   // 选择功能
               .apis(RequestHandlerSelectors.basePackage("com.angindem.controller")) // 选择指定生成 API 接口需要扫描的包
               .paths(PathSelectors.any()) // Swagger 选择 扫描 所有的路径
               .build();   // 注意 记得 build 创建
       return docket;
   }

第三步：设置静态资源映射，否则接口文档页面无法访问

注意！！！ addResourceHandlers 这个方法名不可以随便写，
因为这个方法是继承 WebMvcConfigurationSupport 这个类的，进行了重写

package com.angindem.config;

import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Slf4j
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket docket(){

        // API 接口文档主体信息的创建
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Angindem项目接口文档")    // 项目的标题
                .version("1.0")
                .contact(new Contact("Angindem","http://www.xx22x.com/","xxxxxxxx@qq.com")) // 添加作者个人信息
                .termsOfServiceUrl("http://www.xxx.com/")   // 服务的网址，公司或者个人的访问网址
                .description("这个项目可以使我们更加了解 Swagger ")  // 项目的描述
                .build();   // 注意 记得 build 创建


        // API 接口文档的 接口信息内容的创建
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)   // 放入主题信息
                .select()   // 选择功能
                .apis(RequestHandlerSelectors.basePackage("com.angindem.controller")) // 选择指定生成 API 接口需要扫描的包
                .paths(PathSelectors.any()) // Swagger 选择 扫描 所有的路径
                .build();   // 注意 记得 build 创建
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
//    注意！！！ addResourceHandlers 这个方法名不可以随便写，因为这个方法是继承 WebMvcConfigurationSupport 这个类的，进行了重写
    protected void addResourceHandlers(ResourceHandlerRegistry registry){
        log.info("开始设置静态资源的映射");
//      将 Knife4j 的 Swagger-ui 静态资源放置在 classpath:/META-INF/resources/ 上，其中访问路径为 doc.html
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
//      将 Knife4j 生成的文档等其他资源 放置在  classpath:/META-INF/resources/webjars/** 上
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

尝试验证访问：localhost:8080/doc.html

访问通过，文档出现，配置成功！！！

Swagger 注解的使用

swagger常用注解

注解	说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@Api	用在类上，例如Controler，表示对类的说明
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用
@ApiImplicitParams	用在方法上, 当方法有多个非封装的参数时，添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。
@ApiImplicitParam	用在方法上，主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数

@ApiModel  跟  @ApiModelProperty   一起用

@Api   跟   @ApiOperation    一起用

@ApiModel  与  @ApiModelProperty 使用效果

User 类加入 Swagger 描述

package com.angindem.po;

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

import java.time.LocalDateTime;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "用户类")
public class User {

    @ApiModelProperty(value = "用户ID",required = false,example = "1")
    private Integer id;

    @ApiModelProperty(value = "用户姓名",required = true,example = "张三")
    private String username;

    @ApiModelProperty("用户密码")
    private String password;

    @ApiModelProperty("用户创建时间")
    private LocalDateTime createTime;

    @ApiModelProperty("用户更新时间")
    private LocalDateTime updateTime;
}

使用前

使用后

@Api  与  @ApiOperation    使用效果

UserController 类加入 Swagger 描述

package com.angindem.controller;

import com.angindem.po.User;
import com.angindem.service.IUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
@Api(tags = "用户相关api接口")
public class UserController {

    private final IUserService userService;

    @ApiOperation(value = "获取用户接口",notes = "根据用户参数查询用户")
    @GetMapping("/list")
    public List<User> getUserList(User user){
        return userService.getUserList(user);
    }
}

使用前

使用后

@ApiImplicitParams注解 与  @ ApiImplicitParam 使用效果

非类参数方法加入该注解

@GetMapping("/id")
    @ApiOperation(value = "根据条件获取用户接口",notes = "根据 id 和 用户名 参数查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = false,example = "1"),
            @ApiImplicitParam(name = "name",value = "用户姓名",required = false,example = "李四")
    })
    public List<User> getUserByIdOrUserName(Integer id,String name){
        return userService.getUserByIdOrUserName(id,name);
    }

使用前

使用后

---

上面是 knife4j 旧版 SpringBoot2 的使用方法。由于更新了 适配 SpringBoot3 ，我们需要区分一下用法了，语法上稍微有点变化。在这里我统计一下用法变化哪些。

Swagger 注解的使用

swagger常用注解

旧注解	新注解	说明
@ApiModel	@Schema	用在类上，例如entity、DTO、VO
@ApiModelProperty	@Schema	用在属性上，描述属性信息
@Api	@Tag	用在类上，例如Controler，表示对类的说明
@ApiOperation	@Operation(summary = “foo”, description = “bar”)	用在方法上，例如Controller的方法，说明方法的用途、作用
@ApiImplicitParams	@Parameters	用在方法上, 当方法有多个非封装的参数时，添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。
@ApiImplicitParam	@Parameter	用在方法上，主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数

@Tag

用于说明或定义的标签。

部分参数：

• name ：名称

• description ：描述

---

@Schema

用于描述实体类属性的描述、示例、验证规则等，比如 POJO 类及属性。

部分参数：

• name：名称

• title：标题

• description：描述

• example：示例值

• required：是否为必须

• format：属性的格式。如 @Schema(format = “email”)

• maxLength 、 minLength：指定字符串属性的最大长度和最小长度

• maximum 、 minimum：指定数值属性的最大值和最小值

• pattern：指定属性的正则表达式模式

• type： 数据类型（integer，long，float，double，string，byte，binary，boolean，date，dateTime，password），必须是字符串。如 @Schema=(type=”integer”)

• implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口

---

@Operation

描述 API 操作的元数据信息。常用于 controller 上
部分参数：

• summary：简短描述

• description ：更详细的描述

• hidden：是否隐藏

• tags：标签，用于分组API

• operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称

• parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。

• requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。

• responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性。

---

@Parameters

包含多个 @Parameter 注解，指定多个参数。
代码参考：
包含了 param1 和 param2 两个参数

---

@Parameter

用于描述 API 操作中的参数
部分参数：

• name : 指定的参数名

• in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略

• ParameterIn.QUERY 请求参数

• ParameterIn.PATH 路径参数

• ParameterIn.HEADER header参数

• ParameterIn.COOKIE cookie 参数

• description：参数描述

• required：是否必填，默认为 false

• schema ：参数的数据类型。如 schema = @Schema(type = “string”)

---