OpenAPI3 + Knife4j

CAMELLIA2024-07-152024-07-19

OpenAPI3 + Knife4j

SpringBoot3 + OpenAPI3

在Spring Boot 3中，由于不再支持Springfox，你需要调整你的继承库。
推荐使用springdoc-openapi作为替代方案，它是一个现代化的OpenAPI 3文档生成工具，与Spring Boot很好地集成。

使用OpenAPI3只需确保你的依赖和配置正确，即可成功使用。

OpenAPI3相关依赖

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.6.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-api -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
            <version>2.6.0</version>
        </dependency>

添加注解配置

你只需在你要生成接口文档的控制层添加相应的注解，具体可参考官方文档。

参考博客推荐

@RestController
@RequestMapping("/user")
@Slf4j
@Tag(name = "hello")
public class UserController {

    //.....

}

OpenAPI3 + Knife4j

在配置OpenAPI3 + Knife4j踩了坑，因为使用前端向后端发送请求，但是前端的和后端涉及了跨域，所以我定义了一个Spring MVC 配置类，让它实现了WebMvcConfigurer接口。然后配置跨源资源共享（CORS）、拦截器、视图解析器等各种Spring MVC相关的设置。但是，我添加了一个@EnableWebMvc注解。这导致我配置好Knife4j仍无法访问，报找不到对应资源。

-解决方案：去除@EnableWebMvc即可。

进入正题，如何集成OpenAPI3 + Knife4j？

添加Knife4j依赖

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

这里也有坑，需要注意你SpringBoot的版本，如果不兼容会导致接口请求异常。

添加配置

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: camellia.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

具体可以查阅官方文档

安全措施

在开发和测试阶段我们需要用到openAPI进行接口测试，但是在上线的时候我们需要关闭openAPI配置，防止接口泄露影响程序安全。
此时我们可以在配置文件中指定openAPI在哪种环境激活，在哪种环境关闭。

防止接口暴露信息配置

@Profile("prod")
````


```yml
spring:
  profiles:
    active: dev

配置文件：
创建多个环境的配置文件，比如application-dev.yml和application-prod.yml，并在application.yml中指定激活的环境。
- application.yml：
  1
  2
  3
  spring:
  profiles:
  active: dev
- application-dev.yml（开发环境）：
  1
  2
  3
  springdoc:
  api-docs:
  enabled: true
- application-prod.yml（生产环境）：
  1
  2
  3
  springdoc:
  api-docs:
  enabled: false
配置类：
使用@Profile注解来控制在不同环境下OpenAPI配置的激活。

import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Profile("dev")
public class TestController {

    @GetMapping("/api/test")
    public String testEndpoint() {
        return "This is a test endpoint";
    }
}