【实战】springboot整合swagger及knife4j

前言

对于一个有着资深后端搬砖经验的人来说，最重要的事情就是写API文档了。一个好的API文档不仅仅能够提供给测试人员编写测试用例，也能够直接给前端使用查阅，可以避免很多在系统集成过程中的问题。这不，最近在整合架构的时候留意到了swagger和knife4j。本身swagger提供的web界面可以很好的调试和查阅，现在加上knife4j的API文档自动生成功能，简直不要太好。那么，今天就分享一期springboot整合swagger及knife4j吧！各位大大敬请鉴赏。

技术积累

何为swagger

首先OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

何为knife4j

Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富。早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。

Swagger2与Swagger3注解的主要区别

Swagger3基于OpenAPI Specification 3.0，这个新版本的规范带来了更多的灵活性和表达力。
以下是Swagger2和Swagger3注解的一些主要区别：

通用注解
Swagger2: 使用@Api来注解控制器类，表明该类的路径应该被Swagger文档化。
Swagger3: 不再需要@Api注解。Swagger3使用更自然的方式来扫描类路径，自动包含所有的控制器。

API信息和描述
Swagger2: 通过@ApiInfo和@ApiOperation注解来提供API的信息和操作描述。
Swagger3: 使用@Tag注解来替代@Api，并且通过@Operation注解来提供操作的描述。

路径和操作注解
Swagger2: 使用@ApiOperation来描述一个HTTP操作，@ApiImplicitParam和@ApiImplicitParams用于描述参数。
Swagger3: 引入了@Operation注解来描述HTTP操作，@Parameter注解用于描述参数。

参数注解
Swagger2: 参数注解是通过@ApiParam或@ApiImplicitParam来描述。
Swagger3: 使用@Parameter注解来描述参数，它提供了更丰富的属性，如schema、example和content。

请求体和响应体注解
Swagger2: 使用@ApiModel和@ApiModelProperty注解来描述请求和响应的数据模型。
Swagger3: 引入了@Schema注解来描述数据模型，提供了更多的细节和配置选项。

安全和授权注解
Swagger2: 使用@ApiResponses、@ApiResponse、@ApiOperation等注解来描述响应和错误码。
Swagger3: @ApiResponse注解仍然存在，但是现在可以包含更多的信息，如媒体类型和例子。

springboot整合swagger及knife4j

导入maven依赖

<!--Swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!--knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

yaml配置

knife4j 3.* 的版本会跟 springboot 3.6.* 版本冲突，以下是解决冲突的办法
在yaml文件中加入以下配置即可

server:
  port: 8888
spring:
  profiles:
    active: dev
  mvc:
    pathmatch:
      # Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher
      matching-strategy: ant_path_matcher
knife4j:
  enable: true #开启增强配置
  basic: #基本的登录认证
    enable: true
    username: admin
    password: 123456
      

编写配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * SwaggerConfig
 * @author senfel
 * @version 1.0
 * @date 2024/3/27 16:04
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket initDocket(Environment env) {
        //设置要暴漏接口文档的配置环境
        //设置要显示的Swagger环境
        Profiles profile = Profiles.of("test","dev");
        //获取项目的环境：
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = env.acceptsProfiles(profile);
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                //是否启动swagger 默认为true ,如果为false，则Swagger不能再浏览器中访问
                .enable(flag)
                .select()
                  //RequestHandlerSelectors,配置要扫描接口的方式
//                .apis(RequestHandlerSelectors.any()):扫描全部
//                .apis(RequestHandlerSelectors.none()):不扫描
//                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)):扫描类上的注解，参数是一个注解的反射对象
//                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)):扫描方法上的注解
                //指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.example.ccedemo.controller"))
                //paths()过滤什么路径(url)
//                .paths(PathSelectors.ant("/pm/**")) 就是在localhost:8080/pm后面的路径
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //不过滤
                .paths(PathSelectors.any())
                .build();
                //右上角 组（有几个Docket，有几个组）
//                .groupName();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("接口文档")
                .contact(new Contact("senfel", "", "XXXX@sina.cn"))
                .version("V1.0")
                .license("Apache 2.0")
                .build();
    }
}

编写实体和接口

import io.swagger.annotations.ApiModel;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * Dept
 * @author senfel
 * @version 1.0
 * @date 2024/3/27 16:23
 */
@Data
@ApiModel(description = "部门")
@AllArgsConstructor
@NoArgsConstructor
public class Dept {

    @Schema(description = "主键")
    private Long id;

    @Schema(description = "部门名")
    private String name;
}

import com.example.ccedemo.entity.Dept;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * DeptController
 * @author senfel
 * @version 1.0
 * @date 2024/3/27 16:25
 */
@RestController
@Api(tags = "部门管理")
@RequestMapping("/sys/")
public class DeptController {


    /**
     * 获取部门
     * @param dept
     * @author senfel
     * @date 2024/3/27 16:34
     * @return org.springframework.http.ResponseEntity<com.example.ccedemo.entity.Dept>
     */
    @GetMapping("/getDept")
    @ApiOperation(value = "获取部门")
    public ResponseEntity<Dept> get(@RequestParam Dept dept){
        System.err.println(dept.getName());
        return ResponseEntity.ok(dept);
    }
}

效果展示

浏览器访问http://localhost:8888/swagger-ui/即可访问到swagger3初始页面

输入配置文件中的用户名和密码

浏览器访问http://localhost:8888/doc.html即可访问knife4j初始页面