1.引入依赖

创建项目后，在 pom.xml 文件中引入 Swagger3 的相关依赖。回忆一下，我们集成 Swagger2 时，引入的依赖如下： 

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

而在 Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

而这部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加两项不同依赖，而 Swagger3 只用添加一项依赖就可以了。

除此之外还有一个依赖与上述Swagger3 功能一样：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.3</version>
</dependency>

 1.1.springfox-boot-starter与springdoc-openapi-ui的区别

1. springfox-boot-starter:

   • 这是Springfox团队开发的一个库，用于集成Swagger到Spring Boot项目中。
   • 版本3.0.0是适用于Swagger 3的版本，支持Swagger 3的新特性和规范。
   • 该库提供了一组注解和类，用于配置和生成Swagger文档，并提供了与Spring MVC集成的功能。
   • 通常与Springfox的其他模块一起使用，如 springfox-swagger-ui 和 springfox-swagger2。

2. springdoc-openapi-ui:

   • 这是一个由社区维护的库，用于集成OpenAPI（以前称为Swagger）到Spring Boot项目中。
   • 版本1.6.3是适用于OpenAPI 3的版本，支持OpenAPI 3的新特性和规范。
   • 该库提供了一组注解和类，用于配置和生成OpenAPI文档，并提供了一个集成了Swagger UI的Web界面。
   • 与Springfox不同，springdoc-openapi-ui更专注于OpenAPI规范，提供了更多与OpenAPI规范对齐的功能和特性。

总的来说，如果你的项目使用Swagger 3（现在被重命名为OpenAPI 3），你可以选择使用 springfox-boot-starter 或者 springdoc-openapi-ui，具体选择取决于你更喜欢哪种库的风格和功能。

1.2使用Knife4j作为UI界面时需要导入一下依赖：

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

com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter 是 Knife4j 对 Swagger 3 的增强，它也提供了自己的注解和配置。通常来说，Knife4j 提供了更丰富的 UI 功能和配置选项，使得生成的 API 文档更加易读和美观。

2.  配置Swagger

在Spring Boot项目中创建一个配置类SwaggerConfig，并添加Swagger的配置信息。

@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("进销存管理系统").contact(new Contact()).description("我的API文档").version("v1"));}
}

yaml文件配置如下：

#swagger3文档配置
springdoc:swagger-ui:enabled: true#参数扁平化处理（swagger界面实体属性可以当做params参数正常显示）default-flat-param-object: true

这样配置好了之后就可以正常使用注解了

使用注解方式如下：

接口controller:

@Slf4j
@Tag(name = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {@Autowiredprivate UserManager userManager;/*** //TODD* 系统登录** @author: * @date: 2024-04-05 13:03:40* @param: * @param* @return: ServiceVO**/@Operation(summary = "系统登录")@PostMapping("/login")public ServiceVO login(@RequestBody User user, HttpSession session)  {log.info("login user: " + user.toString());return userManager.login(user,session);}
}

实体类以及vo对象：

@Data
@Schema(description = "业务类型元数据表saveDto")
public class BasicElDataDto {@Schema(description = "主键新增不传")@TableId(value = "pk_id", type = IdType.AUTO)private String pkId;@Schema(description = "业务类型")private String serviceType;@Schema(description = "字段名称")private String elName;@Schema(description = "字段类型")private String elType;

3. 注解说明

Swagger3的注解与Swagger2有所不同，以下是一些常用注解的对照表：

4. 访问Swagger UI

启动您的Spring Boot应用后，您可以通过以下地址访问Swagger UI：

http://localhost:8080/doc.html
http://localhost:8080/swagger-ui/index.html