Springboot整合knife4j

猫哥说

已于 2023-04-23 21:29:50 修改

阅读量3.8k

点赞数

于 2023-04-18 11:44:22 首次发布

本文链接：https://blog.csdn.net/baidu_33256174/article/details/130217302

版权

SpringBoot 专栏收录该内容

8 篇文章 0 订阅

订阅专栏

本文介绍knife4j的用法，如何整合到springboot项目中

文章目录

前言
环境搭建
基本配置
常用注解
测试

前言

参考文档：

在项目开发中，自测和联调时，一篇详细通用的接口文档显得尤为重要，不仅提高了开发效率，而且避免了无效沟通，保证了流程的规范性。
Knife4j跟Swagger用法基本一样，UI界面设计更加漂亮可用。

环境搭建

版本对应关系：
在这里插入图片描述
application.yml文件配置：
Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher，因此需要配置pathmatch。

server:
  port: 9203

spring:
  application:
    name: learn-api
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

引入依赖：

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

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

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

基本配置

文档基础信息

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:03
 * @Desc: 文档基础信息
 */
@Data
@Builder
@ToString
public class Knife4jProperties {
    /**
     * API文档生成基础路径
     */
    private String apiBasePackage;
    /**
     * 是否要启用登录认证
     */
    private boolean enableSecurity;
    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档描述
     */
    private String description;
    /**
     * 文档版本
     */
    private String version;
    /**
     * 文档联系人姓名
     */
    private String contactName;
    /**
     * 文档联系人网址
     */
    private String contactUrl;
    /**
     * 文档联系人邮箱
     */
    private String contactEmail;

}

将Knife4j基础配置抽取成抽象类，对于Properties参数单独配置

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:00
 * @Desc:
 */
public abstract class BaseKnife4jConfig {

    @Bean
    public Docket docket(){
        Knife4jProperties properties = swaggerProperties();
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo(properties))
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getApiBasePackage()))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo(Knife4jProperties swaggerProperties) {
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
                .version(swaggerProperties.getVersion())
                .build();
    }

    /**
     *
     * 增加如下配置可解决Spring Boot 6.x 与Swagger 3.0.0 不兼容问题
     * @param webEndpointsSupplier
     * @param servletEndpointsSupplier
     * @param controllerEndpointsSupplier
     * @param endpointMediaTypes
     * @param corsProperties
     * @param webEndpointProperties
     * @param environment
     * @return
     */
    @Bean
    public WebMvcEndpointHandlerMapping handlerMapping(WebEndpointsSupplier webEndpointsSupplier,
                                                     ServletEndpointsSupplier servletEndpointsSupplier,
                                                     ControllerEndpointsSupplier controllerEndpointsSupplier,
                                                     EndpointMediaTypes endpointMediaTypes,
                                                     CorsEndpointProperties corsProperties,
                                                     WebEndpointProperties webEndpointProperties,
                                                     Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(),
                new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
    }

    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }

    /**
     * 自定义Swagger配置
     */
    public abstract Knife4jProperties knife4jProperties();
}

继承BaseKnife4jConfig，单独实现knife4jProperties函数，自定义属性值，这样设计的优点：

在微服务开发中，每个微服务都有接口函数，将knife4j抽取成一个单独的公共module，上层直接引入后，自定义属性值。

/**
 * @Author: Yangmiao
 * @Date: 2023/4/18 10:27
 * @Desc: knife4j配置
 */
@Configuration
@EnableOpenApi
public class Knife4jConfig extends BaseKnife4jConfig {
    @Override
    public Knife4jProperties knife4jProperties() {
        return Knife4jProperties.builder()
                .apiBasePackage("com.ym.learn.api")
                .title("Api接口文档")
                .description("Api接口文档")
                .contactName("ym")
                .version("1.0")
                .enableSecurity(false)
                .build();
    }
}

常用注解

@Api    用在请求的类上表示对类(controller类)的说明。tags=“说明该类的作用，可以在UI界面上看到的注解”，value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation    用在请求的方法(controller类的方法)上说明方法的用途和作用。value=“说明方法的用途、作用”，notes=“方法的备注说明”
@ApiModel    用于响应类(javaBean类)上表示一个返回响应数据的信息
@ApiModelProperty    用在属性上，描述响应类的属性(javaBean类的方法或属性)
@ApiImplicitParams    用在请求的方法(controller类的方法)上，表示一组参数说明
@ApiImplicitParam    用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
@ApiResponses    用在请求的方法(controller类的方法)上，表示一组响应
@ApiResponse    用在@ApiResponses注解中，用于表达一个的响应信息
@ApiIgnore    用于类或者方法(controller类的方法或controller类)上，可以不被swagger显示在页面上
@ApiParam    作用在参数、方法和字段(cotroller类的方法参数)上，类似@ApiImplicitParam

    个别注解详解：
    ①其中@ApiParam和@ApiImplicitParam的功能是相同的，但是@ApiImplicitParam的适用范围更广

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）    
    dataType：参数类型，默认String，其它值dataType="Integer"       
    defaultValue：参数的默认值


@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

@ApiParam    作用在参数、方法和字段上
    name：参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
    value：参数简单描述
    defaultValu：描述参数默认值
    allowableValues：可接收参数值限制，有三种方式,取值列表，取值范围
    required：是否为必传参数, false:非必传; true:必传
    access：参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
    allowMultiple：指定参数是否可以通过多次出现来接收多个值
    hidden：隐藏参数列表中的参数
    example：非请求体(body)类型的单个参数示例
    example：参数示例，仅适用于请求体类型的请求
    type：添加覆盖检测到类型的功能
    format：添加提供自定义format格式的功能
    allowEmptyValue：添加将格式设置为空的功能
    readOnly：添加被指定为只读的能力
    collectionFormat：添加使用 array 类型覆盖 collectionFormat 的功能

/**
 * @Author: Yangmiao
 * @Date: 2023/4/9 22:45
 * @Desc:
 */
@RestController
@Api(tags = "hello测试接口")
public class HelloController {

    @ApiOperation(value = "hello测试")
    @GetMapping("/hello")
    public String hello() {
        return "Hello World.";
    }

    @Autowired
    private LoginUserHolder loginUserHolder;

    @GetMapping("/currentUser")
    public UserDTO currentUser() {
        return loginUserHolder.getCurrentUser();
    }
}