springboot整合swagger

Spring Boot 2.3.3 可以使用 Springfox Swagger 3 进行整合，具体步骤如下：

---

1. 添加 Maven 依赖

在 pom.xml 中添加 springfox-boot-starter 依赖：

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

注意：Springfox 3 只支持 OpenAPI 3 规范，不支持 Spring Boot 2.6 及以上版本。

---

2. Swagger 配置

创建 SwaggerConfig 配置类：

package com.work.sample.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.function.Predicate;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // OpenAPI 3
                .apiInfo(apiInfo())
                .select()
               // .apis(RequestHandlerSelectors.basePackage("com.work.sample.web.controller")) // 扫描 Controller 包
                .apis(customBasePackages(
                        "com.work.sample.web.controller.order",
                        "com.work.sample.web.controller.price",
                        "com.work.sample.web.controller.stock"
                ))
                .paths(PathSelectors.any()) // 生成所有 API 文档

                .build()
                .globalRequestParameters(globalHeaders()) // 添加全局请求头
                .useDefaultResponseMessages(false) // 关闭默认返回信息，防止意外错误
                .directModelSubstitute(Object.class, java.lang.Void.class) // 避免不规范的 $ref;
                ;
    }


    /**
     * 自定义支持多个包的 RequestHandlerSelectors
     */
    private Predicate<RequestHandler> customBasePackages(String... basePackages) {
        return input -> Arrays.stream(basePackages)
                .anyMatch(basePackage -> RequestHandlerSelectors.basePackage(basePackage).test(input));
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2.3.3 Swagger API 文档")
                .description("API 说明")
                .version("1.0")
                .build();
    }
    /**
     * 添加全局请求头 Authorization
     */
    private List<RequestParameter> globalHeaders() {
        return Collections.singletonList(
                new RequestParameterBuilder()
                        .name("Authorization")
                        .description("Bearer Token")
                        .in(ParameterType.HEADER)
                        .required(false) // 设置为 true，表示所有接口都必须带上该参数
                        .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                        .build()
        );
    }

}

---

3. 创建 Controller

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return "User " + id;
    }

    @ApiOperation("创建用户")
    @PostMapping
    public String createUser(@RequestBody User user) {
        return "User Created: " + user.getName();
    }
}

User 对象

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户对象")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;

    @ApiModelProperty(value = "用户名", example = "张三")
    private String name;

    @ApiModelProperty(value = "用户性别")
    private Sex sex; // 嵌套对象

    // Getter 和 Setter 省略
}

Sex 枚举

import io.swagger.annotations.ApiModel;

@ApiModel(description = "性别枚举")
public enum Sex {
    MALE, FEMALE
}

---

4. 访问 Swagger UI

启动项目后，访问：

• Swagger UI: http://localhost:8080/swagger-ui/
• API 文档（JSON 格式）: http://localhost:8080/v3/api-docs

---

5. 兼容 Spring Boot 2.6+（可选）

如果你的项目升级到 Spring Boot 2.6+，可能会遇到 Swagger 404，需要在 application.yml 中添加：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

---

package com.work.sample.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.function.Predicate;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // OpenAPI 3
                .apiInfo(apiInfo())
                .select()
               // .apis(RequestHandlerSelectors.basePackage("com.work.sample.web.controller")) // 扫描 Controller 包
                .apis(customBasePackages(
                        "com.work.sample.web.controller.order",
                        "com.work.sample.web.controller.price",
                        "com.work.sample.web.controller.stock"
                ))
                .paths(PathSelectors.any()) // 生成所有 API 文档
                .build();
    }
    /**
     * 自定义支持多个包的 RequestHandlerSelectors
     */
    private Predicate<RequestHandler> customBasePackages(String... basePackages) {
        return input -> Arrays.stream(basePackages)
                .anyMatch(basePackage -> RequestHandlerSelectors.basePackage(basePackage).test(input));
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2.3.3 Swagger API 文档")
                .description("API 说明")
                .version("1.0")
                .build();
    }

}
```java