Knife4j/Swagger管理项目API

日常开发工作中，前后端分离已经成为主流，API接口成为前后端的纽带，项目集成Knife4j可以带来以下优点：

• 提高开发效率： 自动生成 API 文档和客户端代码，减少了手动文档编写和接口调用代码编写的时间。
• 文档一致性： 自动生成的文档与实际代码同步更新，保持文档与代码的一致性，避免了文档过时的问题。
• 易于维护： 统一的 API 规范使得 API 易于理解、易于维护，便于团队协作
• 交互式测试： 提供了交互式的 API 测试界面，方便开发人员测试 API 的各种操作。
  并且 Spring Boot 集成 Knife4j 也是十分方便，本文介绍如何在Spring Boot项目中集成/使用 Knife4j。
  官方传送门

基本：

1. 引入依赖
2. 使用配置配置

一、Maven引入依赖

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

重要提示：
Spring Boot 3 发生了较大的改变，所以引入 Knife4j 依赖的时候，需要查看项目的Spring Boot 版本。 官方Knife4j版本参考

二、配置文件

application-knife4j.yml 参考

knife4j:
#  控制是否启用 Knife4j 的功能
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.knife4j.demo.new3

项目启动后，访问 http://ip:port/doc.html 即可查看文档

如果需要更详细的配置，可以参考 官方增强模式配置信息

重要：生产环境需要杜绝开放api文档，我的项目配置一般是通过 spring.config.import 管理的，所以直接不引入 application-knife4j.yml 实现的。

三、使用代码配置

更推荐使用配置文件的方式使用 Knife4j。

java代码：

@Configuration
@EnableSwagger2WebMvc
@Profile("!prod")
@Slf4j
public class Knife4jConfiguration {

    @Bean
    public Docket docket() {
        log.debug("Configuring Swagger API documentation");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的API文档")
                .description("API接口文档")
                .version("1.0.0")
                .build();
    }
}

备注：杜绝生产开发api文档，通过 @Profile 和配置 spring.profiles.active=prod实现。
小注： 使用spring.profiles.active=prod，并不意味着你一定要创建 application-prod.yml文件！