在 Spring Boot 3.2.10 中集成 Swagger 3，可以通过以下步骤实现：
- 项目结构
- 添加依赖： 在
pom.xml文件中添加 Swagger 3 的依赖：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.1.0</version>
</dependency>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.1.0</version>
</dependency>
</dependencies>
-
创建 Swagger 配置类： 在你的项目中创建一个 Swagger 配置类，用于配置 Swagger 的基本信息。
package com.atguigu.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; @Configuration public class OpenApiConfig { @Bean public OpenAPI openApi() { return new OpenAPI() .info(new Info() .title("文档标题") .description("文档描述") .contact(new Contact().name("作者").email("邮箱").url("可以写你的博客地址或不填")) .version("v2.0")); } } -
访问 Swagger UI： 启动你的 Spring Boot 应用程序后，可以通过以下 URL 访问 Swagger UI：
http://localhost:8080/swagger-ui/index.html# -
API 文档： 你可以通过以下 URL 访问生成的 API 文档：
http://localhost:8080/v3/api-docs -
配置 CORS（如果需要） ： 如果你的前端和后端是分开的，可以需要配置 CORS。你可以在配置类中添加如下内容：
HelloController.java
package com.atguigu.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
@RestController
@Slf4j
@Tag(name = "HelloController")
public class HelloController {
@GetMapping("/hello")
@Operation(summary = "hello", description = "hello")
public String hello() {
log.info("hello!!!");
return "hello!!!";
}
}
application.properties
spring.application.name=springboot_mvc_test
springdoc.api-docs.enabled=true
springdoc.swagger-ui.persist-authorization=true
SpringDoc 是一个用于在 Spring Boot 应用程序中生成 API 文档的库，主要用于与 OpenAPI 规范（以前称为 Swagger）兼容。你提供的配置项主要用于控制 API 文档的生成和 Swagger UI 的行为。以下是这两个配置项的作用：
1. springdoc.api-docs.enabled=true
-
作用：
- 启用或禁用 API 文档的生成。
- 当设置为
true时，SpringDoc 会自动扫描你的 Spring Boot 应用中的所有 RESTful 控制器，并根据其定义生成 OpenAPI 规范的文档。 - 生成的文档可以通过访问
http://localhost:8080/v3/api-docs（假设使用默认端口）来查看。
2. springdoc.swagger-ui.persist-authorization=true
-
作用：
- 这个配置项控制 Swagger UI 的授权数据持久化。
- 当设置为
true时，Swagger UI 会在浏览器的本地存储中保存用户的授权信息（例如，OAuth 2.0 令牌、API 密钥等），这样即使用户关闭或刷新浏览器，授权数据仍然会被保留。 - 这对于需要认证的 API 特别有用，因为用户不需要每次都重新输入授权信息，改善了用户体验。
总结
- API 文档生成：通过启用 API 文档，可以使开发人员、测试人员和其他利益相关者更容易了解和使用你的 API。
- 授权信息持久化：改善 Swagger UI 的使用体验，尤其是在需要频繁进行 API 调用的场景下。
这些配置项为开发和使用 RESTful API 提供了便利，提高了文档化和用户体验的效率。
注意注释区别
@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden
@ApiImplicitParam -> @Parameter
@ApiImplicitParams -> @Parameters
@ApiModel -> @Schema
@ApiModelProperty(hidden = true) -> @Schema(accessMode = READ_ONLY)
@ApiModelProperty -> @Schema
@ApiOperation(value = "foo", notes = "bar") -> @Operation(summary = "foo", description = "bar")
@ApiParam -> @Parameter
@ApiResponse(code = 404, message = "foo") -> @ApiResponse(responseCode = "404", description = "foo")
