在线API文档knife4j的使用方法

1、简介

knife4j是国人开发的一个为Java MVC框架生成Api文档的解决方案,前身是swagger-bootstrap-ui,取名knif4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

2、准备工作

• 2.1 在pom文件中添加依赖

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

• 2.2 在application.propertieso配置文件中添加配置

knife4j.enable=true

说明：

• knife4j.enable=false;这个配置表示禁用了 Knife4J 的增强功能。在这种情况下，应用可能仍然会使用默认的 Swagger UI 页面，或者完全不显示任何 API 文档界面，这取决于其他配置以及项目的具体实现。

• knife4j.enable=true;这个配置则表示启用了 Knife4J 的增强功能。这意味着当你访问应用的文档页面时，展示的将是 Knife4J 提供的增强版本的 UI 界面，它通常提供了比原始 Swagger UI 更多的功能和更好的体验。

• 2.3 创建配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    //配置Swagger2的Docket的Bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
                .apis(RequestHandlerSelectors.basePackage("cn.tedu.ivos"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }

    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("智慧车辆运营项目")
                // 文档描述信息
                .description("智慧车量运营项目在线API文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

3、测试使用

3.1 controller层的操作

在controller层中添加@Api注解，在类中的每一个操作方法的上面添加@ApiOperation、@ApiImplicitParamz注解，例子如下：

@Api(tag="公告模块")
@RestController
@RequestMapping("v1/notice")
public class NoticeController(){
    @Autowired
    private NoticeMapper noticeMapper;

    //增加公告
    @ApiOperation(value = "增加公告")
    @ApiImplicitParam(name = "notice", value = "公告对象", required = true)
    @PostMapping("/api/insert")
    public JsonResult insertNotice(@RequestBody @Validated Notice notice){
        noticeMapper.insert(notice);
        return new JsonResult(200,"添加成功");
     }


    //删除公告，实质将status修改为0
    @ApiOperation(value = "删除公告")
    @ApiImplicitParam(name = "id", value = "公告id", required = true)
    @PutMapping("api/update1/{id}")
    public JsonResult updateNotice1(@PathVariable("id") Long id){
       noticeMapper.update1(id);
       return new JsonResult(200,"删除成功");
     }


    //根据id修改公告
    @ApiOperation(value = "修改公告")
    @ApiImplicitParam(name = "notice", value = "公告对象", required = true)
    @PutMapping("api/update2")
    public JsonResult updateNotice2(@RequestBody Notice notice){
       noticeMapper.update2(notice);
       return new JsonResult(200,"更新成功");
    }


    //查询公告
    @ApiOperation(value = "查询公告")
    @ApiImplicitParam(name = "id", value = "公告id", required = true)
    @GetMapping("/api/select/{id}")
    public JsonResult selectNotice(@PathVariable("id") Long id){
        Notice notice=noticeMapper.select(id);
        return new JsonResult(notice);
    }
 

    //批量删除公告
    @ApiOperation(value = "批量删除公告")
    @ApiImplicitParam(name = "ids", value = "公告id数组", required = true)
    @DeleteMapping("/api/delete")
    public JsonResult deleteNotice(@RequestBody Long[] ids){
        System.out.println(Arrays.toString(ids));
        noticeMapper.delete(ids);
        return new JsonResult(200,"删除成功");
    }
 }

 3.2  访问操作

上述步骤完成后，启动启动类，通过 http://localhost:8080/doc.html 即可访问在线API文档。