关于Knife4j框架

文章目录

一、Knife4j框架是什么？
二、使用步骤
总结

提示：以下是本篇文章正文内容，下面案例可供参考

一、Knife4j框架是什么？

Knife4j框架是一款基于Swagger 2框架的、能够基于项目中的控制器的代码来生成在线API文档的框架，另外，此框架还有调试功能，可以向服务器端发送请求，并获取响应结果。

二、使用步骤

关于此框架，要使之能够使用，需要：

添加依赖
添加配置类
在application.properties中添加1条配置

关于依赖的代码：



    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.9

关于配置类：

@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    
    private String basePackage = "cn.tedu.csmall.product.controller";
    
    private String groupName = "product";
    
    private String host = "http://java.tedu.cn";
    
    private String title = "XX商城在线API文档--商品管理";
    
    private String description = "XX商城在线API文档--商品管理";
    
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    
    private String contactName = "Java开发者";
    
    private String contactUrl = "http://java.doc.cn";
    
    private String contactEmail = "java@doc.cn";
    
    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();
    }

}

关于application.properties中的配置：

# 开启Knife4j框架的增强模式
knife4j.enable=true

注意：

当前项目的Spring Boot版本必须是2.6以下的版本（2.6不可用）
- 如果要使用更高版本的Spring Boot，必须使用更高版本的Knife4j
在配置类中的basePackage必须是控制器类所在的包，记得需要修改

在开发实践中，还应该对在线API文档进行细化，需要在控制器及相关类中进行一些配置：

在控制器类上添加@Api注解，配置tags属性，此属性是String类型的
在控制器类中处理请求的方法上添加@ApiOperation注解，配置value属性，此属性是String类型的
在控制器类中处理请求的方法上添加@ApiOperationSupport注解，配置order属性，此属性是int类型的
- 此属性用于排序，数据越小越靠前，不建议使用1位的数字
在控制器类中处理请求的方法上，不要再使用没有限制请求方式的@RequestMapping，建议使用@GetMapping或@PostMapping
如果处理请求的方法中，如果参数是封装的数据类型，应该在此类型的各属性上添加@ApiModelProperty注解，以配置对参数的说明
如果处理请求的方法中，如果参数并没有封装，则需要使用@ApiImplicitParams和@ApiImplicitParam这2个注解组合来配置
- 注意：一旦配置了@ApiImplicitParam，原本的提示的值会被覆盖，应该完整的配置各属性
  示例：

@Api(tags = "04. 相册管理模块")
@Slf4j
@RestController
@RequestMapping("/albums")
public class AlbumController {

    @Autowired
    private IAlbumService albumService;

    public AlbumController() {
        log.info("创建控制器：AlbumController");
    }

    // 添加相册
    // http://localhost:9080/albums/add-new?name=XiaoMi&description=TestDescription&sort=69
    @ApiOperation("添加相册")
    @ApiOperationSupport(order = 100)
    @PostMapping("/add-new")
    public String addNew(@Validated AlbumAddNewDTO albumAddNewDTO) {
        log.debug("开始处理【添加相册】的请求：{}", albumAddNewDTO);
        albumService.addNew(albumAddNewDTO);
        return "添加相册成功！";
    }

    // http://localhost:9080/albums/9527/delete
    @ApiOperation("根据id删除相册")
    @ApiOperationSupport(order = 200)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "相册id", dataType = "long", required = true)
    })
    @PostMapping("/{id:[0-9]+}/delete")
    public String delete(@PathVariable Long id) {
        log.debug("开始处理【删除相册】的请求：id={}", id);
        albumService.deleteById(id);
        return "删除相册成功！";
    }
    
}

完整的配置示例–AlbumAddNewDTO：

@Data
public class AlbumAddNewDTO implements Serializable {

    
    @ApiModelProperty(value = "相册名称", example = "小米80的相册", required = true)
    @NotNull(message = "必须提交相册名称！")
    private String name;

    
    @ApiModelProperty(value = "相册简介", example = "小米80的相册的简介", required = true)
    @NotNull(message = "必须提交相册简介！")
    private String description;

    
    @ApiModelProperty(value = "自定义排序序号", example = "88", required = true)
    @NotNull(message = "必须提交自定义排序序号！")
    @Range(max = 99, message = "自定义排序序号必须是0~99之间的值！")
    private Integer sort;

}

完成以上配置后，启动项目，通过 /doc.html 即可访问在线API文档。
http://localhost:9080/doc.html#/home

总结

例如：以上就是今天要讲的内容，本文仅仅简单介绍了如何使用Knife4j框架

关于Knife4j框架

Java相关栏目本月热门文章