【实战】springboot整合swagger及knife4j

文章目录

- 前言
- 技术积累
- - 何为swagger
  - 何为knife4j
  - Swagger2与Swagger3注解的主要区别
- springboot整合swagger及knife4j
- - 导入maven依赖
  - yaml配置
  - 编写配置类
  - 编写实体和接口
- 效果展示

前言

对于一个有着资深后端搬砖经验的人来说，最重要的事情就是写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: devmvc:pathmatch:# Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatchermatching-strategy: ant_path_matcher
knife4j:enable: true #开启增强配置basic: #基本的登录认证enable: trueusername: adminpassword: 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 {@Beanpublic 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);}
}