Knife4j

Knife4j完全遵循了Swagger的使用方式，所以可以无缝切换。

第一步，在pom.Xml文件中添加Knife4的依赖。

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

不需要再引入 Swagger 所需的 springfox-boot-starter了，因为 Knife4j 的 starter 里面已经加入过了。

第二步，创建一个 Java 配置类（例如 Knife4jConfig.java），并使用 @EnableKnife4j 注解启用 Knife4j。

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //apis： 添加swagger接口提取范围
                .apis(RequestHandlerSelectors.basePackage("www.xxx.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("技术接口文档")
                .description("采用主流的互联网技术架构、全新的UI设计")
                .contact(new Contact("qtp", "https://tim-qtp.github.io/blog","linkstim23@gmail.com"))
                .version("v1.0")
                .build();
    }
}

或者你也可以不创建 Java 配置类，通过在 application.yml 文件中设置属性来达到相同的目的。

这里是技术派中配置 Knife4j 的示例：

knife4j:
  enable: true
  openapi:
    title: 技术接口文档
    description: 采用主流的互联网技术架构、全新的UI设计
    version: 1.0.0
    concat: qtp
    url: https://tim-qtp.github.io/blog
    license: Apache License 2.0
    license-url: https://stackoverflow.com/
    email: linkstim23@gmail.com
    group:
      admin:
        group-name: 后台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.qtp.forum.web.admin
      front:
        group-name: 前台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.qtp.forum.web.front

在以前的版本中，我们需要在配置文件中手动使用 @EnableKnife4j 来使用增强，自 2.0.6 版本后，只需要在配置文件中配置 knife4j.enable=true 即可。

逐一解释下这些属性的作用：

①、knife4j.enable: 设置为 true 以启用 Knife4j，将在应用程序中启用 Knife4j UI。

②、knife4j.openapi: 这个属性包含了 Swagger API 文档的基本元数据信息，例如标题、描述、版本等。

• title: API 文档的标题。
• description: API 文档的详细描述。
• version: API 文档的版本号。
• concat: API 文档的作者信息。
• license: API 文档的许可证类型。
• license-url: API 文档许可证的链接。
• email: API 文档作者的联系邮箱。

③、knife4j.group: 定义 API 分组。这里有两个分组：admin 和 front。

admin: 后台接口分组。

• group-name: 分组名称。
• api-rule: 分组规则，这里使用的是包规则。
• api-rule-resources: 指定包名，Knife4j 将扫描此包下的所有 API 接口并将它们添加到此分组。

第三步，在测试类中添加 knife4j 的接口。

@ApiOperation("测试 Knife4j")
@RequestMapping(value ="/testKnife4j", method = RequestMethod.POST)
public String testKnife4j() {
    return "秦一又帅又丑";
}

①、@ApiOperation：用于描述一个具体的 API 操作。通常用于标注在 Controller 类的方法上。它有以下三个主要属性：

• value：API 操作的简短描述，会显示在 API 文档中。
• notes：API 操作的详细描述
• tags：API 操作的标签，用于对 API 进行分类和分组。

例如：

@ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户详细信息")

②、@ApiParam：用于描述 API 操作的参数。通常用于标注在 Controller 类的方法参数上。它有以下主要属性：

• name：参数名称。
• value：参数描述。
• required：指示参数是否是必需的，默认为 false。
• defaultValue：参数的默认值。
• allowableValues：允许的参数值范围。

例如：

public ResponseEntity<User> getUser(@ApiParam(value = "用户 ID", required = true) @PathVariable("id") Long id) {
    // ...
}

③、@ApiModel：用于描述一个 API 操作返回的数据模型或请求数据模型。通常用于标注在实体类或 DTO 类上。它有以下主要属性：

• value：模型名称。
• description：模型描述。

例如：

@ApiModel(value = "用户", description = "用户详细信息")
public class User {
    // ...
}

第四步，运行项目，然后在浏览器地址栏输入 http://localhost:8080/doc.html 就可以看到 API 文档了。