当前位置：首页 > 文章列表 > 文章 > java教程 > SpringBoot整合Swagger配置指南

SpringBoot整合Swagger配置指南

2025-07-12 23:21:29 0浏览收藏

编程并不是一个机械性的工作，而是需要有思考，有创新的工作，语法是固定的，但解决问题的思路则是依靠人的思维，这就需要我们坚持学习和更新自己的知识。今天golang学习网就整理分享《Spring Boot整合Swagger配置教程》，文章讲解的知识点主要包括，如果你对文章方面的知识点感兴趣，就不要错过golang学习网，在这可以对大家的知识积累有所帮助，助力开发能力的提升。

在Spring Boot项目中整合Swagger的核心步骤包括：引入依赖、配置Docket Bean、添加注解以实现API文档化，并可通过安全认证和隐藏接口等进一步优化。1. 引入Maven依赖，推荐使用springfox-boot-starter 3.0.0版本；2. 创建配置类SwaggerConfig，定义Docket Bean并设置API基本信息、扫描路径和包；3. 启动应用后访问/swagger-ui/index.html查看文档界面；4. 添加securitySchemes和securityContexts以支持JWT认证；5. 使用@ApiIgnore注解或paths()方法隐藏特定API；6. 遇到问题时检查版本兼容性、路径配置及依赖冲突，确保正确启用@EnableOpenApi注解。

Spring Boot整合Swagger详细配置教程

在Spring Boot项目里整合Swagger，说白了就是为了把我们那些散落在代码里的API接口，用一种清晰、交互性强的方式展现出来。核心操作其实就那么几步：引入依赖、配置一个Docket Bean，然后通过注解告诉Swagger哪些接口需要被文档化。这玩意儿一旦配好，你就能在浏览器里直接看到所有接口，还能在线调试，对前后端联调的效率提升，那可不是一星半点。我个人觉得，这几乎是现代微服务开发里不可或缺的一环，能省下大量沟通成本。

解决方案

通常，我开始一个新项目时，第一步就是把Swagger的依赖加进去。这就像给你的API文档找个好管家，省心。

1. 引入Maven依赖

如果你用的是Maven，在pom.xml里添加：

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

这里我推荐使用springfox-boot-starter 3.0.0版本，它基于OpenAPI 3规范，相对老旧的Swagger2来说，功能更完善，也更符合当前趋势。当然，如果你的项目比较老，还在用Spring Boot 1.x或者Spring Cloud Finchley之类的，可能得退回到springfox-swagger2和springfox-swagger-ui的2.x版本，那时候配置起来稍微有点不一样，但核心思想是通的。

2. 创建Swagger配置类

接下来，你需要创建一个配置类来告诉Spring Boot如何初始化Swagger。我一般会命名为SwaggerConfig。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi; // 对应Springfox 3.0.0
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi // 启用OpenAPI支持，如果是Springfox 2.x，这里是@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 指定API文档类型为OpenAPI 3.0
                .apiInfo(apiInfo()) // 设置API基本信息
                .select() // 选择要生成文档的API
                .apis(RequestHandlerSelectors.basePackage("com.yourcompany.project.controller")) // 指定扫描的包
                // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) // 或者扫描带有@RestController注解的类
                .paths(PathSelectors.any()) // 扫描所有路径
                // .paths(PathSelectors.regex("/api/.*")) // 或者只扫描/api/开头的路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("你的项目API文档") // 文档标题
                .description("这是一个关于XXXX项目的API接口文档，希望能帮助你快速理解和使用接口。") // 详细描述
                .contact(new Contact("你的名字", "http://yourwebsite.com", "your.email@example.com")) // 维护者信息
                .version("1.0") // API版本
                .build();
    }
}

这里面最关键的就是那个Docket Bean。DocumentationType.OAS_30表示我们用的是OpenAPI 3规范。apiInfo()方法就是用来配置文档的标题、描述、联系方式和版本号这些元数据。select()方法是重点，它定义了哪些API会被Swagger扫描并生成文档。我通常用RequestHandlerSelectors.basePackage()来指定控制器所在的包，这样比较精确。当然，你也可以用withClassAnnotation(RestController.class)来扫描所有带有@RestController注解的类，或者用PathSelectors.regex()来过滤特定的URL路径。

3. 访问Swagger UI

配置完成后，启动你的Spring Boot应用。然后，在浏览器中访问：http://localhost:8080/swagger-ui/index.html (如果你用的是Springfox 3.0.0)。如果是Springfox 2.x版本，通常是http://localhost:8080/swagger-ui.html。

你就能看到一个漂亮的交互式API文档界面了。

如何为Swagger文档添加安全认证（如JWT Token）？

说实话，大部分实际项目里，API都是需要认证的，比如用JWT Token。如果Swagger文档不能模拟这个认证过程，那在线调试的功能就大打折扣了。所以，给Swagger加上安全认证支持，这几乎是必做项。

我们可以在Docket配置中添加securitySchemes和securityContexts。

import java.util.Collections;
import java.util.List;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.service.contexts.SecurityContext;

// ... 其他import和类定义不变 ...

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourcompany.project.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes()) // 添加安全方案
                .securityContexts(securityContexts()); // 添加安全上下文
    }

    private List<ApiKey> securitySchemes() {
        // 配置JWT认证方式：在请求头中传递Token
        return Collections.singletonList(new ApiKey("Authorization", "Authorization", "header"));
    }

    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("/.*")) // 对所有路径都生效
                        .build()
        );
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Collections.singletonList(new SecurityReference("Authorization", authorizationScopes));
    }

    // ... apiInfo() 方法不变 ...
}

这里我做了几件事：

securitySchemes(): 定义了一个名为Authorization的ApiKey，告诉Swagger，有一个认证方式叫Authorization，它会从请求的header中获取值，这个值的键也是Authorization（通常是Bearer your_token这种形式）。
securityContexts(): 这是一个列表，每个SecurityContext定义了哪些API路径需要应用哪些安全方案。forPaths(PathSelectors.regex("/.*"))表示所有路径都应用这个安全方案。
defaultAuth(): 定义了AuthorizationScope，这里我简单地给了个global范围，表示可以访问所有资源。

配置好后，你会发现Swagger UI界面上多了一个“Authorize”按钮。点击它，输入你的JWT Token（通常是Bearer开头），然后你再调试接口时，请求头里就会自动带上这个Token了。这真的太方便了，省去了每次手动复制粘贴Token的麻烦。

如何定制Swagger UI界面或隐藏特定API？

有时候，我们不希望所有的API都暴露在Swagger文档里，或者想让UI界面看起来更符合品牌风格。这些需求，Swagger也考虑到了。

1. 隐藏特定API

最简单粗暴的方法是使用@ApiIgnore注解。如果你有一个控制器或者一个方法，你压根不想让它出现在文档里，直接在类或方法上加上@ApiIgnore就行。

import springfox.documentation.annotations.ApiIgnore;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@ApiIgnore // 整个控制器都不会出现在文档中
public class InternalController {

    @GetMapping("/internal/data")
    public String getInternalData() {
        return "Sensitive internal data";
    }
}

@RestController
public class PublicController {

    @GetMapping("/public/info")
    public String getPublicInfo() {
        return "Public information";
    }

    @ApiIgnore // 这个方法不会出现在文档中
    @GetMapping("/public/hidden-method")
    public String getHiddenMethod() {
        return "This method is hidden.";
    }
}

另一种方法是，在Docket配置中通过paths()进行更细粒度的控制，比如只暴露/api/v1/开头的接口：

// ... Docket 配置中 ...
.paths(PathSelectors.regex("/api/v1/.*")) // 只显示/api/v1/开头的路径
// .paths(PathSelectors.ant("/api/v1/**")) // 也可以用ant风格的路径匹配
.build();

这样，那些不符合规则的接口就不会出现在文档里了。

2. 定制Swagger UI

Springfox 3.0.0默认的UI路径是/swagger-ui/index.html。如果你想修改这个路径，或者进行一些UI上的简单定制，可以通过application.properties或application.yml来配置。

# application.properties
springdoc.swagger-ui.path=/docs
springdoc.api-docs.path=/api-docs # 改变原始API JSON的路径

这里我用了springdoc的配置，因为Springfox 3.0.0在内部实际上是基于springdoc-openapi的。通过springdoc.swagger-ui.path，你可以把访问路径改成http://localhost:8080/docs。

如果你想更深入地定制UI，比如修改样式、添加Logo，那就得稍微麻烦一点了。你需要下载Swagger UI的静态资源，然后放到Spring Boot的src/main/resources/static目录下，覆盖掉默认的资源文件。这通常涉及到修改index.html，引入自定义的CSS或JS文件。我个人觉得，除非有非常强的品牌要求，否则默认的UI已经足够用了，没必要折腾太多。毕竟，我们的主要目标是API文档的可用性，而不是UI有多花哨。

集成Swagger时常见的坑与解决方案？

在我自己的项目实践中，集成Swagger虽然总体顺利，但也遇到过一些让人头疼的小问题。

1. 版本冲突或不兼容

这是最常见的问题。比如，你用了Spring Boot 2.6.x，却引入了老旧的Springfox 2.x版本，或者Springfox 3.0.0和某些Spring Cloud版本之间会有依赖冲突。

症状： 应用启动失败，报错信息通常是NoClassDefFoundError、NoSuchMethodError或者Bean创建失败。Swagger UI无法访问，或者显示空白。
解决方案：
- 检查Spring Boot和Springfox版本兼容性。 Springfox 3.0.0通常与Spring Boot 2.x系列（尤其是2.3.x及以上）配合较好。如果遇到问题，可以尝试升级或降级Spring Boot版本，或者调整Springfox的版本。
- 排除传递性依赖。 有时，其他库会引入旧版本的Swagger依赖。你可以在pom.xml中使用标签来排除它们。例如：
```
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
```
- 清理Maven/Gradle缓存。 mvn clean install 或 gradle clean build 后，删除本地Maven仓库中相关的Springfox/Swagger目录，再重新构建。

2. Swagger UI无法访问或No handler found

你启动了应用，但访问/swagger-ui/index.html或/swagger-ui.html时却出现404错误。

症状： 浏览器显示404，或者控制台报错No handler found for GET /swagger-ui.html。
解决方案：
- 检查@EnableOpenApi或@EnableSwagger2注解是否已添加。 这是启用Swagger的关键。
- 确认你的Spring Boot版本。 Spring Boot 2.6.0及以上版本默认禁用了路径匹配策略，这可能会影响Swagger UI的访问。你需要在application.properties中添加：
```
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
```
  或者，如果你用的是Springfox 3.0.0，并且Spring Boot版本较高，可以尝试使用springdoc-openapi-ui替代springfox-boot-starter，它对新版Spring Boot的兼容性更好。
- 检查端口和上下文路径。 确保你访问的localhost:8080是正确的，如果你的应用有上下文路径（比如/my-app），那么完整路径应该是http://localhost:8080/my-app/swagger-ui/index.html。

3. API文档内容不全或显示异常

你发现有些控制器或方法没有出现在文档中，或者参数、返回值显示不正确。

症状： 某些API缺失，或者参数类型、描述与实际不符。
解决方案：
- 检查Docket的select()配置。 确保basePackage、apis、paths等配置正确地覆盖了你的API。是不是包名写错了？是不是路径匹配规则太严格了？
- 检查API注解。 确保你的控制器和方法使用了正确的Spring MVC注解（@RestController, @GetMapping, @PostMapping等），以及Swagger相关的注解（@Api, @ApiOperation, @ApiParam, @ApiModelProperty等）。
- 自定义类型解析器。 对于一些复杂或自定义的Java类型，Swagger可能无法正确解析。你可能需要实现AlternateTypeRule来自定义它们的显示方式。这个就比较高级了，通常在遇到特殊情况时才需要。