刀锋利器：Knife4j助你轻松驾驭API文档

**技术派项目源码地址 : **

• **Gitee : **技术派 - https://gitee.com/itwanger/paicoding
• **Github : 技术派 - https://github.com/itwanger/paicoding **

Knife4j :

• 官方文档：https://doc.xiaominfo.com/
• 码云地址：https://gitee.com/xiaoym/knife4j
• 示例地址：https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

整合Knife4j

引入依赖

<knife4j.version>4.0.0</knife4j.version>

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

编写配置文件 法①

@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.paicoding.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("技术派")
                .description("一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统，采用主流的互联网技术架构、全新的UI设计、支持一键源码部署，拥有完整的文章&教程发布/搜索/评论/统计流程等，代码完全开源，没有任何二次封装，是一个非常适合二次开发/实战的现代化社区项目👍 。")
                .contact(new Contact("沉默王二", "https://paicoding.com","www.qing_gee@163.com"))
                .version("v1.0")
                .build();
    }
}

编写配置文件 法②

knife4j:
  enable: true
  openapi:
    title: 技术派
    description: 一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统，采用主流的互联网技术架构、全新的UI设计、支持一键源码部署，拥有完整的文章&教程发布/搜索/评论/统计流程等，代码完全开源，没有任何二次封装，是一个非常适合二次开发/实战的现代化社区项目👍 。
    version: 1.0.0
    concat:
      - 一灰灰 | 楼仔 | 沉默王二
      - https://paicoding.com
      - https://github.com/itwanger/paicoding
    license: Apache License 2.0
    license-url: https://github.com/itwanger/paicoding/blob/main/License
    email: bangzewu@126.com
    group:
      admin:
        group-name: 后台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.paicoding.forum.web.admin
      front:
        group-name: 前台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.paicoding.forum.web.front

配置名词解释

①、knife4j.enable: 设置为 true 以启用 Knife4j，将在应用程序中启用 Knife4j UI。
②、knife4j.openapi: 这个属性包含了 Swagger API 文档的基本元数据信息，如标题、描述、版本等。

• title: API 文档的标题。
• description: API 文档的详细描述。
• version: API 文档的版本号。
• concat: API 文档的作者信息。包括作者名、网站和 GitHub 仓库。
• license: API 文档的许可证类型。
• license-url: API 文档许可证的链接。
• email: API 文档作者的联系邮箱。

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

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

front: 前台接口分组，它下面的属性不再赘述，和 admin 一样。

注解三兄弟 : @ApiOperation、@ApiParam、@ApiModel

1. @ApiOperation：用于描述一个具体的 API 操作。通常用于标注在 Controller 类的方法上。

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

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

2. @ApiParam：用于描述 API 操作的参数。通常用于标注在 Controller 类的方法参数上。

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

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

3. @ApiModel：描述一个 API 操作返回的数据模型, 通常用于标注在实体类或 DTO 类上。

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

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

启动项目, 访问Knife4j测试

**访问Knife4j地址 : **http://localhost:8080/doc.html

Knife4j优点

支持全局参数

支持离线文档

支持API搜索