springboot 整合 knife4j-openapi3

筑梦情缘i

于 2024-05-04 12:01:36 发布

阅读量1.3k

点赞数 18

文章标签： spring boot 后端 java

本文链接：https://blog.csdn.net/qq_49444793/article/details/138438250

版权

适用于：项目已使用shiro安全认证框架，整合knife4j-openapi3

1.引入依赖

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

2.配置类

package com.xidian.contest.configure;


import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;




@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info().title("竞赛报名管理系统接口文档")
                        .description("竞赛报名管理系统接口文档")
                        .version("v1.0")
                        .contact(new Contact().name("TYJ").url("localhost:8085/login")))
                        .externalDocs(new ExternalDocumentation()
                        .description("Github example code")
                        .url("https://github.com/"));
    }

}

3.yaml配置

# spring-doc 接口文档
springdoc:
  api-docs:
    enabled: true
    #分组配置
  group-configs:
    - group: 'default'
    #匹配的路径
      paths-to-match: '/**'
      #扫描的包
      packages-to-scan: com.xidian.contest.controller
  default-flat-param-object: true
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

4.shiro拦截权限设置

definition.addPathDefinition("/doc.html", "anon");
definition.addPathDefinition("/swagger-resources", "anon");
definition.addPathDefinition("/v3/api-docs/**", "anon");
definition.addPathDefinition("/webjars/**", "anon");
definition.addPathDefinition("/doc.html#/**", "anon");
definition.addPathDefinition("/swagger-ui.html", "anon");
definition.addPathDefinition("/static/**", "anon");

5.启动项目

http://localhost:+端口号+/doc.html

6.常用注解

@Tag

用于说明或定义的标签。
部分参数：
●name：名称
●description：描述

@Schema

用于描述实体类属性的描述、示例、验证规则等，比如 POJO 类及属性。
部分参数：
●name：名称
●title：标题
●description：描述
●example：示例值
●required：是否为必须
●format：属性的格式。如 @Schema(format = "email")
●maxLength 、 minLength：指定字符串属性的最大长度和最小长度
●maximum 、 minimum：指定数值属性的最大值和最小值
●pattern：指定属性的正则表达式模式
●type：数据类型（integer，long，float，double，string，byte，binary，boolean，date，dateTime，password），必须是字符串。如 @Schema=(type="integer")
●implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口

@Content

内容注解。部分参数：
●mediaType：内容的类型。比如：application/json
●schema：内容的模型定义，使用 @Schema 注解指定模型的相关信息。

@RequestBody(content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))) 
@PostMapping("/users")
public void createUser(User user) {
    // ...
}

@Hidden

某个元素（API 操作、实体类属性等）是否在 API 文档中隐藏。如，getUserById 方法不会显示在 API 文档中

@Hidden
@GetMapping("/users/{id}")
public User getUserById(@PathVariable("id") Long id) {
    // ...
}

代码参考：使用在实体类字段中，实现对敏感信息或不需要公开的元素进行隐藏。如：用户密码字段

@Schema(description = "用户")
public class User {
    @Schema(description = "用户id")
    private Long id;

    @Schema(description = "用户名")
    private String name;

    @Hidden
    @Schema(description = "用户密码")
    private String password;

    // ...
}

@Operation

描述 API 操作的元数据信息。常用于 controller 上部分参数：
●summary：简短描述
●description ：更详细的描述
●hidden：是否隐藏
●tags：标签，用于分组API
●operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称
●parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。
●requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。
●responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性。

@Operation(
  summary = "操作摘要",
  description = "操作的详细描述",
  operationId = "operationId",
  tags = "tag1",
  parameters = {
    @Parameter(name = "param1", description = "参数1", required = true),
    @Parameter(name = "param2", description = "参数2", required = false)
  },
  requestBody = @RequestBody(
    description = "请求描述",
    required = true,
    content = @Content(
      mediaType = "application/json",
      schema = @Schema(implementation = RequestBodyModel.class)
    )
  ),
  responses = {
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
    @ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
  }
)
@Tag(name = "标签1")
@ApiResponses(value = {
  @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
  @ApiResponse(responseCode = "400", description = "錯誤", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
})
public void yourOperation() {
  // 逻辑
}

详细参考：

@Operation(summary = "文件分页显示接口")
    @Parameters({
            @Parameter(
                    name = "pageNum",
                    description = "分页数",
                    required = true,
                    in = ParameterIn.QUERY,
                    schema = @Schema(type = "Integer")
            ),
            @Parameter(
                    name = "pageSize",
                    description = "每页大小",
                    required = true,
                    in = ParameterIn.QUERY,
                    schema = @Schema(type = "Integer")
            ),
            @Parameter(
                    name = "name",
                    description = "要查询文件名称",
                    in = ParameterIn.QUERY,
                    schema = @Schema(type = "string")
            )
    })
    @RequiresRoles("admin")
    @GetMapping("/page")
    public IPage<Files> findPage(@RequestParam Integer pageNum,
                                 @RequestParam Integer pageSize,
                                 @RequestParam(defaultValue = "") String name)

@Parameter

用于描述 API 操作中的参数部分参数：
●name : 指定的参数名
●in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略
        ○ParameterIn.QUERY 请求参数
        ○ParameterIn.PATH 路径参数
        ○ParameterIn.HEADER header参数
        ○ParameterIn.COOKIE cookie 参数
●description：参数描述
●required：是否必填，默认为 false
●schema ：参数的数据类型。如 schema = @Schema(type = "string")
代码参考：

@Parameters({
  @Parameter(
    name = "param1",
    description = "Parameter 1 description",
    required = true,
    in = ParameterIn.PATH,
    schema = @Schema(type = "string")
  ),
  @Parameter(
    name = "param2",
    description = "Parameter 2 description",
    required = true,
    in = ParameterIn.QUERY,
    schema = @Schema(type = "integer")
  )
})

@Parameters

包含多个 @Parameter 注解，指定多个参数。代码参考：包含了 param1 和 param2 两个参数
@RequestBody
API 请求的注解
●description：请求信息的描述
●content：请求的内容
●required：是否必须

@ApiResponse

API 的响应信息。部分参数：
●responseCode：响应的 HTTP 状态码
●description：响应信息的描述
●content：响应的内容
代码参考：

@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
    // ...
}