Java Spring Boot项目中集成Swagger完整步骤

在Spring Boot项目中集成Swagger可以方便地生成API文档,支持在线测试接口。以下是详细的集成步骤:


1. 添加依赖

pom.xml中添加Swagger的依赖(以Springfox为例,这是最常用的Swagger实现):

XML 复制代码
<!-- Springfox Swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version> <!-- 注意版本兼容性 -->
</dependency>

<!-- Springfox Swagger UI(提供可视化界面) -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

注意​:

  • 如果使用Spring Boot 3.x,Springfox可能不完全兼容(因为Springfox已停止维护)。推荐改用 SpringDoc OpenAPI(见下文替代方案)。
  • Springfox 3.0.0需要Java 8+,且与Spring Boot 2.x兼容性较好。

2. 配置Swagger

创建一个配置类(如SwaggerConfig.java),启用Swagger并配置基本信息:

java 复制代码
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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定扫描的包路径(替换为你的Controller包路径)
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                // 指定路径匹配规则(这里匹配所有路径)
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API文档")
                .description("RESTful API接口文档")
                .version("1.0")
                .build();
    }
}

3. 访问Swagger UI

启动Spring Boot应用后,访问以下URL查看Swagger界面:

  • Swagger UI : http://localhost:8080/swagger-ui.html
  • API JSON文档 : http://localhost:8080/v2/api-docs

4. 替代方案:SpringDoc OpenAPI(推荐用于Spring Boot 3.x)​

如果使用Spring Boot 3.x,建议改用 ​SpringDoc OpenAPI​(支持OpenAPI 3.0标准),步骤如下:

1. 添加依赖
XML 复制代码
<!-- SpringDoc OpenAPI UI -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version> <!-- 检查最新版本 -->
</dependency>
2. 访问界面
  • Swagger UI : http://localhost:8080/swagger-ui/index.html
  • OpenAPI JSON : http://localhost:8080/v3/api-docs
3. 自定义配置(可选)​

通过application.ymlapplication.properties配置:

XML 复制代码
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha

5. 常见问题

  1. 404错误​:

    • 检查依赖版本是否与Spring Boot版本兼容。
    • 确保Controller类有@RestController@Controller注解,且方法有@RequestMapping或其衍生注解(如@GetMapping)。
  2. Spring Boot 3.x兼容性​:

    • Springfox已不再维护,强烈建议使用SpringDoc OpenAPI。
  3. 分组API​:

    • 可以通过多个Docket Bean实现API分组(Springfox)或使用SpringDoc的GroupedOpenApi

6. 示例项目结构

html 复制代码
src/main/java
└── com.example
    ├── controller
    │   └── UserController.java  # 示例Controller
    └── config
        └── SwaggerConfig.java   # Swagger配置类

通过以上步骤,你可以快速在Spring Boot中集成Swagger,生成清晰的API文档并支持在线测试。如果需要更高级的功能(如OAuth2安全集成、自定义UI等),可以参考Springfox官方文档SpringDoc官方文档

Swagger常见访问地址

Swagger本地常见访问地址主要取决于Swagger版本是否集成增强UI​(如Knife4j),具体如下:

1. Swagger 2.x(旧版,如Springfox)​

  • 默认路径
    http://localhost:8080/swagger-ui.html
    • 若项目有上下文路径 (如/api),则需追加路径:
      http://localhost:8080/api/swagger-ui.html

2. Swagger 3.x(新版,如SpringDoc OpenAPI)​

  • 默认路径
    http://localhost:8080/swagger-ui/index.html
    • 若集成Knife4j 增强UI,则路径为:
      http://localhost:8080/doc.html
相关推荐
你好,我叫C小白4 分钟前
C语言 常量,数据类型
c语言·开发语言·数据类型·常量
小红帽2.022 分钟前
从ioutil到os:Golang在线客服聊天系统文件读取的迁移实践
服务器·开发语言·golang
22:30Plane-Moon1 小时前
项目1总结其三(图片上传功能)
ide·spring boot·vue
qq_589568101 小时前
javaweb开发笔记—— 前端工程化
java·前端
Zafir20241 小时前
Qt实现TabWidget通过addTab函数添加的页,页内控件自适应窗口大小
开发语言·c++·qt·ui
阿巴~阿巴~1 小时前
深入解析C++非类型模板参数
开发语言·c++
码农小灰1 小时前
Kafka消息持久化机制全解析:存储原理与实战场景
java·分布式·kafka
向上的车轮2 小时前
Spring Boot生态中ORM对数据治理的支持有哪些?
spring boot·数据治理·orm
程序员鱼皮3 小时前
太香了!我连夜给项目加上了这套 Java 监控系统
java·前端·程序员
L2ncE4 小时前
高并发场景数据与一致性的简单思考
java·后端·架构