跳到主要内容

快速开始

温馨提醒

Knife4jInsight(简单、方便的OpenAPI接口文档私有化聚合平台),地址：http://knife4j.net

如果你对选择Knife4j的版本存在疑惑，可以参考文档Knife4j版本参考

Spring Boot 3​

提示
  • Spring Boot 3 只支持OpenAPI3规范
  • Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
  • JDK版本必须 >= 17
  • 详细Demo请参考knife4j-spring-boot3-demo

首先，引用Knife4j的starter,Maven坐标如下：

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

Gradle坐标如下：

implementation("com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0")

引入之后，其余的配置，开发者即可完全参考springdoc-openapi的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启

部分配置如下:

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

Knife4j更多增强配置明细，请移步文档进行查看

最后，使用OpenAPI3的规范注解，注释各个Spring的REST接口，示例代码如下：

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
       return ResponseEntity.ok(fileResp);
   }
}

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

Spring Boot 2​

提示

OpenAPI2​

OpenAPI2(Swagger)规范是Knife4j之前一直提供支持的版本，底层依赖框架为Springfox,此次在4.0版本开始

Knife4j有了新的变化，主要有以下几点：

  • Springfox版本选择的依然是2.10.5版本，而并非springfox最新3.0.0版本
  • 不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作
  • Spring Boot 版本建议 2.4.0~3.0.0之间

可以使用 knife4j-openapi2-spring-boot-starter,maven 坐标如下：

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

配置yml属性，如下：

knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.knife4j.demo.new3

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

OpenAPI3​

OpenAPI3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本

  • springfox 3.0.0： 同时兼容OpenAPI2以及OpenAPI3，但是停更很久了
  • springdoc-openapi： 兼容OpenAPI3规范，更新速度频繁

Knife4j在只有的OpenAPI3规范中，底层基础框架选择springdoc-openapi项目

针对Springfox3.0.0版本会放弃。

建议开发者如果使用OpenAPI3规范的话，也尽快迁移过来。

可以使用 knife4j-openapi3-spring-boot-starter,maven 坐标如下：

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

引入jar包后，同上面的Spring Boot 3版本使用方式一样，进行配置即可。

最后由 xiaoyumin 于 更新