springboot3.3.4集成接口文档Swagger、Knife4j

原创已于 2024-11-11 21:49:22 修改 · 921 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#java

于 2024-11-05 21:16:48 首次发布

SpringBoot 专栏收录该内容

13 篇文章

订阅专栏

1、springboot3.3.4集成Swagger

1、导包

<!--springboot3.3.4集成Swagger-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

2、不需要额外的配置类、访问 http://localhost:8080/swagger-ui.html

3、在controller类、方法、参数上使用相关注解

@Tag：用于描述控制器或方法的标签。
@Parameter：用于描述方法参数。
@ApiResponse：用于描述方法的响应。
@Schema：用于描述模型类的字段

2、springboot3.3.4集成knife4j

1、导包

<!--springboot3.3.4集成Knife4j，knife4j-spring-boot-starter版本须在4.0.0以上，当前方式未测试，包不太好找-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2、访问地址 http://localhost:8080/doc.html

3、在controller类、方法、参数上使用相关注解

@Api：用于描述控制器。
@ApiOperation：用于描述方法。
@ApiParam：用于描述方法参数。
@ApiModel：用于描述模型类。
@ApiModelProperty：用于描述模型类的字段。

3、springboot3.1.6集成Knife4j

1、导包

	<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>
        
        <!-- springBoot3.16适配的knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>

2、application.yml添加配置

# 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.bx.wms.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

3、controller类上添加相关注解

@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);
   }
}

4、访问地址：http://ip:port/doc.html，例如：http://localhost:8080/doc.html

5、如果有拦截器、过滤器，需放行这些路径

"/doc.html/","/v3/api-docs/**","/doc.html#/**",
"/favicon.ico","/webjars/**"