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
相关推荐
杨DaB1 小时前
【SpringMVC】拦截器,实现小型登录验证
java·开发语言·后端·servlet·mvc
近津薪荼1 小时前
c++详解(宏与内联函数,nullptr)
开发语言·c++
自由鬼2 小时前
如何处理Y2K38问题
java·运维·服务器·程序人生·安全·操作系统
_oP_i5 小时前
RabbitMQ 队列配置设置 RabbitMQ 消息监听器的并发消费者数量java
java·rabbitmq·java-rabbitmq
Monkey-旭5 小时前
Android Bitmap 完全指南:从基础到高级优化
android·java·人工智能·计算机视觉·kotlin·位图·bitmap
我爱996!5 小时前
SpringMVC——响应
java·服务器·前端
小宋10216 小时前
多线程向设备发送数据
java·spring·多线程
天若有情6736 小时前
【python】Python爬虫入门教程:使用requests库
开发语言·爬虫·python·网络爬虫·request
大佐不会说日语~7 小时前
Redis高频问题全解析
java·数据库·redis