Knife4j实现注解自动生成_mybatisx-generator 生成knife4j 注释-CSDN博客

本文链接：https://blog.csdn.net/m0_61229395/article/details/136520067

文章目录

前言

对于程序员来说，不仅要会写代码，也要会写文档，可读性高的文档可以在前后端项目中提高前端和后端开发人员的效率，开发人员可以更加清晰地思考接口的设计和实现，从而提高代码的质量和可维护性，也可以方便测试人员进行接口测试，同时也方便后期对接口进行维护和升级。

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

Knife4j是什么？

Knife4j是一款基于Swagger 2的在线API文档框架，是日常开发中很常用的框架，用于Java MVC框架集成Swagger以生成API文档。其核心功能主要包括：根据Swagger规范详细说明接口文档，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息；提供在线接口联调的强大功能，可以自动解析当前接口参数，并返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。

使用步骤

官方参考：https://doc.xiaominfo.com/docs/quick-start

1.引入依赖

openapi2版本依赖如下：

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

OpenApi2版本Springboot版本最好是大于2.4且小于3，如果要使用OpenApi3版本Springboot版本要大于3，坐标版本2.0.9改成3开头的即可。

2.配置

添加一个配置类，实现控制类目录等配置：

@Configuration
@EnableSwagger2WebMvc
public class ApiDocConfig {
    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "org.youguess.freshmandemo.controller";
    private String title = "API文档";
    /**
     * 简介
     */
    private String description = "平台在线API文档";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 联系人
     */
    private String contactName = "你猜我";
    /**
     * 联系网址
     */
    private String contactUrl = "https://blog.csdn.net/m0_61229395";
    /**
     * 联系邮箱
     */
    private String contactEmail = "W2878082959@163.com";
    /**
     * 版本号
     */
    private String version = "1.0";

    /**
     * 创建并配置 Docket 对象，用于 Swagger 文档的生成和展示
     */
    @Bean(value = "docket")
    public Docket docket() {
        // 定义分组名称
        String groupName = "1.0.0";

        // 创建并配置 Docket 对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 设置 API 文档信息
                .groupName("系统")//分组名
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage)) // 设置扫描的 Controller 包路径
                .paths(PathSelectors.any()) // 设置 API 路径匹配规则
                .build();

        return docket;
    }

    /**
     * 创建并配置 ApiInfo 对象，用于设置 Swagger 文档的基本信息
     *
     * @return 配置好的 ApiInfo 对象
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title) // 设置标题
                .description(description) // 设置简介
                .license("Powered By AJun")
                .licenseUrl("http://127.0.0.1")
                .termsOfServiceUrl(termsOfServiceUrl) // 设置服务条款 URL
                .contact(new Contact(contactName, contactUrl, contactEmail)) // 设置联系信息
                .version(version) // 设置版本号
                .build();
    }
}

yml文件配置：

#如果要开启knife4j增强功能，则设置为true
knife4j:
  enable: true
#如果出现版本不兼容的问题则添加一下配置
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

Knife4j的增强功能主要体现在以下几个方面：

在线调试：Knife4j提供了强大的在线接口联调功能，开发者可以直接在文档页面进行接口调试，无需额外编写测试代码。它会自动解析当前接口参数，并返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者快速验证接口的正确性。
接口排序：Knife4j支持接口排序功能，可以按照不同的规则对接口进行排序，使得接口文档更加清晰易读。排序规则可以针对不同的Controller进行排序，也可以针对同一个Controller中的不同方法进行排序。
导出离线文档：Knife4j支持导出离线文档功能，可以将接口文档导出为Markdown格式的文件，方便开发者在本地进行查阅和备份。这对于需要频繁查阅文档的开发者来说非常有用。
安全性增强：Knife4j提供了灵活的权限控制功能，可以在配置文件中指定哪些环境下的接口文档需要屏蔽。这对于生产环境下的接口文档保护非常有用，可以避免敏感信息泄露和非法访问。

添加WebMVC配置：

由于Knife4j默认通过host:port/doc.html路径访问UI页面，所以要正常显示，要先配置Springboot的静态资源映射。

添加类继承WebMvcConfigurationSupport类

@Configuration
public class MyMvcConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/resources/")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/faceImages/**").addResourceLocations("classpath:/studentFaces/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        super.addResourceHandlers(registry);
    }
}

3.在Controller类中添加注解

介绍几个常用注解

@Api 修饰controller类

@ApiOperation 修饰controller里的方法

@ApiImplicitParam 修饰方法参数

@ApiResponses 修饰方法返回值

@ApiParam 修饰方法的参数

@ApiModel 修饰实体类

@ApiModelProperty 修饰实体类里的字段

示例：

@RestController
@RequestMapping("users")
@Api(tags="学生信息相关Api")
public class studentController {
    @Autowired
    private studentService studentServer;
    @Autowired
    private studentDao dao;
    @ApiOperation(value = "返回学生信息",response = student.class,httpMethod = "GET")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "学号",required = true,type = "String")
            //,@ApiImplicitParam(........
    )
    @ApiResponses(
            @ApiResponse(code = 0,message ="学生实体" ,response = student.class)
            //@@ApiResponse(........
    )
    @RequestMapping("/info/{id}")
    public R info(@PathVariable("id") String id){
        student user = studentServer.getById(id);

        return R.ok().put("data", user);
    }
}