SpringBoot 3 整合Swagger3.0或Knife4j

躺平打工人

已于 2025-02-26 11:47:18 修改

阅读量826

点赞数 10

文章标签： spring boot java mybatis

于 2024-01-10 17:26:13 首次发布

本文链接：https://blog.youkuaiyun.com/xu344526/article/details/135506693

版权

本文介绍了SpringBoot3.0版本后如何集成SwaggerUI进行API文档管理和knife4j增强版的配置，包括添加依赖、自定义访问路径、注解迁移以及knife4j的基本认证设置。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

spring boot3.X之后整合swagger添加依赖为

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

默认访问路径：

 http://server:port/swagger-ui/index.html

简单配置

springdoc:
  swagger-ui:
    # 自定义的文档界面访问路径。默认访问路径是/swagger-ui/index.html
    path: /springdoc
    # 一共三个值来控制操作和标记的默认展开设置。它可以是“list”（仅展开标记）、“full”（展开标记和操作）或“none”（不展开任何内容）。
    docExpansion: none
    # 控制“试用”请求的请求持续时间（毫秒）的显示。
    displayRequestDuration: true
    # 控制供应商扩展（x-）字段和操作、参数和架构值的显示。
    showExtensions: true
    # 控制参数的扩展名（pattern、maxLength、minLength、maximum、minminimum）字段和值的显示。
    showCommonExtensions: true
    # 禁用swagger用户界面默认petstore url。（从v1.4.1开始提供）。
    disable-swagger-default-url: true
  api-docs:
    # enabled the /v3/api-docs endpoint
    enabled: true
    # 自定义的文档api元数据访问路径。默认访问路径是/v3/api-docs
    #    path: /springdoc/api
    # 布尔值。在@Schema（名称name、标题title和说明description，三个属性）上启用属性解析程序。
    resolve-schema-properties: true

整合增强版swagger

Knife4j官方文档

Knife4j历史版本

Gateway网关模式-聚合文档

引入依赖

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

简单配置：

#springdoc分组配置可不加
#springdoc:
#  group-configs:
#    - group: '默认分组'
#      paths-to-match: '/**'
#      packages-to-scan: 根目录包名

#knife4j相关配置
knife4j:
  enable: true
  setting:
    language: zh_cn
    swagger-model-name: bean类的名称
  basic:
    enable: true
    # Basic认证用户名
    username: hgh
    # Basic认证密码
    password: a1234567

文档地址：

http://ip:port/doc.html

Swagger2.0到Swagger3.0常用注解变更

swagger2	OpenAPI 3	注解位置
`@Api`	@Tag(name = “接口类描述”)	Controller 类上
`@ApiOperation`	@Operation(summary =“接口方法描述”)	Controller 方法上
`@ApiImplicitParams`	@Parameters	Controller 方法上
`@ApiImplicitParam`	@Parameter(description=“参数描述”)	Controller 方法上 `@Parameters` 里
`@ApiParam`	@Parameter(description=“参数描述”)	Controller 方法的参数上
`@ApiIgnore`	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden
`@ApiModel`	@Schema	实体类上
`@ApiModelProperty`	@Schema	实体属性上