[技术资料]Spring Boot 轻松实现Swagger集成，自动生成API文档

最新推荐文章于 2025-03-27 11:00:28 发布

Doug.

最新推荐文章于 2025-03-27 11:00:28 发布

阅读量1.1k

点赞数 6

分类专栏： SpringBoot 文章标签： spring boot 后端 java

本文链接：https://blog.youkuaiyun.com/liliYoung_/article/details/144194868

版权

SpringBoot 专栏收录该内容

25 篇文章

订阅专栏

Swagger 是一款流行的开源工具，用于生成RESTful API的文档，并提供交互式的API测试界面。在Spring Boot中，集成Swagger非常简单，它不仅能够生成清晰、易懂的API文档，还可以直接在浏览器中测试API接口。本文将介绍如何在Spring Boot项目中集成Swagger，并详细配置其生成API文档的步骤。

1. 配置Swagger依赖

在Spring Boot项目中使用Swagger，首先需要在pom.xml文件中引入Swagger的相关依赖。Springfox 是一个与Spring Boot兼容的Swagger实现库，下面是如何引入它的依赖。

1.1 在 `pom.xml` 中添加 Swagger 依赖

<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>

springfox-swagger2：这是Swagger的核心依赖，用于生成API文档。
springfox-swagger-ui：这是Swagger的UI界面，提供一个Web界面来展示和测试API。

1.2 配置 Swagger

在Spring Boot中，需要创建一个Swagger配置类来启用Swagger功能。该类需要使用@EnableSwagger2注解来启用Swagger支持，并配置API的选择策略。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select() // 配置要扫描的接口
                .apis(RequestHandlerSelectors.any()) // 扫描所有API
                .paths(PathSelectors.any()) // 扫描所有路径
                .build();
    }
}

@Configuration：标记该类为配置类。
@EnableSwagger2：启用Swagger支持。
Docket：Swagger的配置类，通过该类来配置扫描的API接口、路径等信息。
RequestHandlerSelectors.any()：扫描所有的API接口。
PathSelectors.any()：扫描所有的路径。

2. 访问 Swagger UI

配置好Swagger之后，启动Spring Boot应用程序，访问Swagger的UI界面，地址通常为：

http://localhost:8080/swagger-ui.html

在这个界面中，开发者可以看到所有被Swagger识别的API接口，并能够直接调用API进行测试，查看返回的结果。

3. Swagger注解

Swagger不仅可以自动生成API文档，还支持通过注解对接口进行详细描述，提供更友好的文档和API测试体验。以下是一些常用的Swagger注解及其作用：

3.1 `@Api` 注解

@Api注解用于标注类或方法，表示该类或方法是一个API接口，Swagger会将其包含在文档中。

@Api(value = "用户管理接口", description = "提供用户管理的相关功能")
@RestController
@RequestMapping("/users")
public class UserController {
    // API接口...
}

value：接口的名称。
description：对接口的描述信息。

3.2 `@ApiOperation` 注解

@ApiOperation用于描述一个接口方法的作用，Swagger将显示在API文档中。

@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户的详细信息")
@GetMapping("/get/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    // 方法实现...
}

value：接口方法的简短描述。
notes：接口方法的详细描述。

3.3 `@ApiParam` 注解

@ApiParam用于描述接口方法参数，帮助开发者理解参数的用途。

@ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户的详细信息")
@PostMapping("/update")
public ResponseEntity<User> updateUser(@ApiParam(value = "用户ID", required = true) @RequestParam Long id,
                                       @ApiParam(value = "用户数据", required = true) @RequestBody User user) {
    // 方法实现...
}

value：参数的描述。
required：该参数是否是必需的。

3.4 `@ApiResponse` 注解

@ApiResponse注解用于描述接口返回的状态码及其含义。

@ApiOperation(value = "删除用户", notes = "根据用户ID删除指定用户")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "操作成功"),
    @ApiResponse(code = 400, message = "请求参数错误"),
    @ApiResponse(code = 404, message = "用户未找到")
})
@DeleteMapping("/delete/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    // 方法实现...
}

code：HTTP状态码。
message：状态码的描述信息。

4. 高级配置与优化

4.1 Swagger3支持

Spring Boot 2.0+ 默认支持Swagger 3（OpenAPI）。如果需要升级到Swagger 3，建议使用springdoc-openapi而不是springfox-swagger2。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

配置方式和Swagger2类似，可以通过@OpenAPIDefinition注解配置详细的文档信息。

4.2 文档导出

如果需要将Swagger文档导出为PDF或HTML等格式，可以使用一些插件或额外的工具。通过插件可以将文档直接导出成可分享的格式。

4.3 解决Swagger乱码问题

如果在Swagger UI界面出现乱码问题，常见的解决方法包括：

确保你的Spring Boot应用的字符编码是UTF-8。

在application.properties中设置以下属性：

spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true

5. 总结

通过集成Swagger，开发者可以自动生成RESTful API文档，极大地提升开发效率。Swagger不仅能生成文档，还能提供交互式的API测试界面，便于前后端的协作。以下是集成Swagger的关键步骤：

添加依赖：在pom.xml中引入springfox-swagger2和springfox-swagger-ui。
配置Swagger：通过创建SwaggerConfig配置类启用Swagger。
访问Swagger UI：在浏览器中访问http://localhost:8080/swagger-ui.html查看生成的API文档。
使用Swagger注解：通过@Api、@ApiOperation等注解为API接口添加详细说明。

在实际开发中，Swagger不仅能够自动生成文档，还可以通过注解进一步优化API接口的描述，提高文档的可读性和易用性。