Knife4j框架

简介：Knife4j是一款在线API文档框架，可以基于当前项目的控制器类中的配置生成文档，并自带调试功能。通俗来说就是将controller里面请求的接口文档化，便于前端人员熟知请求方式和参数。并且能自动化根据controller的更新而跟新。

用法——

1.添加依赖:

    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.9//该版本适合springBoot2.6以下，springBoot2.6以上需要将版本提升。

2.在主配置文件（`application.properties` / `application.yml`）中开启增强模式（以yml为例）

# Knife4j配置
knife4j:
  # 开启增强模式
  enable: true
#  production: true 禁用该功能，无法访问页面。

3.-添加配置类（是相对固定的代码，复制粘贴即可）

@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
 
    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "cn.shop.controller"; //修改为自己的controller包路径
    /**
     * 分组名称
     */
    private String groupName = "product";
    /**
     * 主机名
     */
    private String host = "";
    /**
     * 标题
     */
    private String title = "";
    /**
     * 简介
     */
    private String description = "在线API文档";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "";
    /**
     * 联系人
     */
    private String contactName = "";
    /**
     * 联系网址
     */
    private String contactUrl = "n";
    /**
     * 联系邮箱
     */
    private String contactEmail = "";
    /**
     * 版本号
     */
    private String version = "1.0.0";
 
    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;
 
    public Knife4jConfiguration() {
        log.debug("创建配置类对象：Knife4jConfiguration");
    }
 
    @Bean
    public Docket docket() {
        String groupName = "1.0.0";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }
}

使用——

1.启动springboot项目

2.网址输入xxx/doc.html（xxx为springBoot的访问路径。如：localhost:9080）

补充——

注解解析：

- @Api：添加在控制器类上，通过此注解的tags属性，可配置管理模块的名称，在配置管理模块名称时，可以在各名称前面添加数字或字母进行序号的排列，使得各管理模块的显示顺序是自定义的顺序
  - 例如：@Api(tags = "1. 相册管理模块")

---

- @ApiOperation：添加在控制器类中处理请求的方法上，通过此注解的`value`属性，可配置业务的名称
  - 例如：@ApiOperation("添加相册")

---

- @ApiOperationSupport：添加在控制器类中处理请求的方法上，通过此注解的order属性（int类型），可配置业务的排序序号，各业务将按照此序号升序排列
  - 例如：@ApiOperationSupport(order = 400)
  - 提示：不建议将序号排列的过于紧凑，否则，不利于在已有的顺序中插入新的内容

---

- @ApiModelProperty：添加在POJO类型的属性上，通过此注解的value属性，可配置属性的名称，通过此注解的required属性，可配置是否必须提交此参数（但不具备检查功能），通过此注解的example属性，可配置示例值（需要注意数据类型的问题，例如数值型的属性不要配置字母或符号作为示例值），通过此注解的dataType属性，可配置数据类型，例如配置为dataType = "long"，但此属性通常不需要配置此属性

    例如：public class AlbumAddNewDTO implements Serializable {
        @ApiModelProperty(value = "相册名称", required = true, example = "小米手机的相册")
        private String name;
    }

---

- @ApiImplicitParam：添加在控制器类中处理请求的方法上，用于对未封装的请求参数进行配置，必须通过此注解的`name`属性，指定配置哪个参数，其它属性的配置可参考@ApiModelProperty中的属性，需要注意的是，一旦通过此注解进行配置，在API文档上显示的数据类型默认是string，对于非字符串类型的属性，应该显式的配置dataType属性

- 例如：@ApiImplicitParam(name = "id", value = "相册ID", required = true, example = "9527", dataType = "long")

---

- @ApiImplicitParams：添加在控制器类中处理请求的方法上，当方法的参数超过1个，且都需要配置API文档说明时，必须将多个@ApiImplicitParam注解配置作为此注解（@ApiImplicitParams）的参数（此注解参数是`@ApiImplicitParam`数组类型）

例如：@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "相册ID", required = true, example = "9527", dataType = "long"),
            @ApiImplicitParam(name = "userId", value = "用户ID", required = true, example = "9527", dataType = "long")
    })
    public String delete(Long id, Long userId) {
        return null;
    }