Knife4j 基础（OpenAPI3+SpringBoot2.7）

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

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

2. 官网

Knife4j官网

Knife4j在实现OpenAPI3规范时，底层基础框架选择 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. 首页

4.2. 接口详情页

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 官方文档 。