springboot项目引入swagger

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 {
    @Bean
    public 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 {

    @Autowired
    private 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