Knife4j 基础（OpenAPI3+SpringBoot2.7）

以你之姓@ 2023-10-15 22:18 94阅读 0赞

## 1. Knife4j基础（OpenAPI3 + SpringBoot2.7） ##

本文按照官方文档，在 `SpringBoot 2.7` 项目中，集成 `Knife4j` 的 `OpenAPI3` 版本。

## 2. 官网 ##

[Knife4j官网][Knife4j]

Knife4j在实现OpenAPI3规范时，底层基础框架选择 `springdoc-openapi` 项目。

[springdoc-openapi 官网][springdoc-openapi]

## 3. 初始化项目 ##

### 3.1. 依赖 ###

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

### 3.2. 配置 ###

#### 3.2.1. yml配置 ####

# spring-doc-openapi项目配置
    spring-doc:
      swagger-ui:
        path: /swagger-ui.html
        tags-sorter: alpha
        operations-sorter: alpha
      api-docs:
        path: /v3/api-docs
      group-configs:
        - group: '默认分组'
          paths-to-match: '/**'
          packages-to-scan: com.example
    
    # knife4j的增强配置，不需要增强可以不配
    knife4j:
      enable: true
      setting:
        enable-footer: false

#### 3.2.2. @Configuration配置 ####

这里的配置，展示在文档首页中，对接口文档进行整体说明。

package com.example.config;
    
    import io.swagger.v3.oas.models.OpenAPI;
    import io.swagger.v3.oas.models.info.Contact;
    import io.swagger.v3.oas.models.info.Info;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    @Configuration
    public class Knife4jConfig {
        
        @Bean
        public OpenAPI customOpenAPI() {
        
            return new OpenAPI()
                    .info(new Info()
                            .title("Knife4j示例项目 - 接口文档")
                            .description("项目简介，支持Markdown格式：`这里是代码标签哦`，**这里是强调哦**")
                            .version("V1.0")
                            .contact(new Contact().name("宋冠巡"))
                    );
        }
    }

### 3.3. 接口注解 ###

演示基本的接口`注解`。

在Controller控制器及内部接口方法中，添加注解。

package com.example.controller;
    
    import io.swagger.v3.oas.annotations.Operation;
    import io.swagger.v3.oas.annotations.Parameter;
    import io.swagger.v3.oas.annotations.Parameters;
    import io.swagger.v3.oas.annotations.enums.ParameterIn;
    import io.swagger.v3.oas.annotations.tags.Tag;
    import org.springframework.lang.Nullable;
    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;
    
    @RestController
    @RequestMapping("index")
    @Tag(name = "首页")
    public class IndexController {
        
    
        @Operation(summary = "向客人问好")
        @Parameter(name = "name", description = "姓名", in = ParameterIn.QUERY)
        @GetMapping("/hello")
        public String sayHi(@RequestParam String name) {
        
            return "Hi:" + name;
        }
    
    
        @Operation(summary = "测试参数可以为空")
        @Parameters({
        
                @Parameter(name = "name", description = "姓名", in = ParameterIn.QUERY)
        })
        @GetMapping("/nullable")
        public String testNullable(@Nullable String name) {
        
            return "Hi:" + name;
        }
    
    }

## 4. 页面效果页面效果 ##

### 4.1. 首页 ###

![在这里插入图片描述][6241514912444c03bd80eb4224cf0a5f.png]

### 4.2. 接口详情页 ###

![在这里插入图片描述][8e7f935ee4ea49d8acad68465040ac31.png]

![在这里插入图片描述][811f1de14d3c47a1a1a2ff1a7c2b7766.png]

## 5. @Parameter(required = false) 无效问题 ##

在`OpenAPI3`中，接口文档默认接口参数必须填写；如果一个参数确实不是必须，要将此接口参数中注明为`@Nullable`。此时，接口文档才会根据 `@Parameter - required` 属性的值，展示参数`是否必须`。

import org.springframework.lang.Nullable;

@Operation(summary = "测试参数可以为空")
        @Parameters({
        
                @Parameter(name = "name", description = "姓名", in = ParameterIn.QUERY)
        })
        @GetMapping("/nullable")
        public String testNullable(@Nullable String name) {
        
            return "Hi:" + name;
        }

## 6. OpenAPI3：Migrating from SpringFox ##

进一步的细节，参考 [springdoc-openapi 官方文档][springdoc-openapi] 。  
![在这里插入图片描述][19d6e4cc6d41471589a8b1108270eb9f.png]

[Knife4j]: https://doc.xiaominfo.com/
[springdoc-openapi]: https://springdoc.org/
[6241514912444c03bd80eb4224cf0a5f.png]: https://img-blog.csdnimg.cn/6241514912444c03bd80eb4224cf0a5f.png
[8e7f935ee4ea49d8acad68465040ac31.png]: https://img-blog.csdnimg.cn/8e7f935ee4ea49d8acad68465040ac31.png
[811f1de14d3c47a1a1a2ff1a7c2b7766.png]: https://img-blog.csdnimg.cn/811f1de14d3c47a1a1a2ff1a7c2b7766.png
[19d6e4cc6d41471589a8b1108270eb9f.png]: https://img-blog.csdnimg.cn/19d6e4cc6d41471589a8b1108270eb9f.png