Swagger详解API 文档

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。
Swagger 主要包含了以下三个部分：
Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档。
Swagger Codegen：它可以通过为 OpenAPI规范定义的任何 API 生成服务器存根和客户端 SDK 来简化
构建过程。
2、为什么要使用 Swagger
在前后端分离开发以后，维持一份及时更新且完整的 Rest API 文档，能够极大的提高的开发效率。传统意
义上的文档都是后端开发人员手动编写的，一般是以Doc或者是md等形式离线传播。而在开发阶段，接口修改
非常频繁，就很难保证文档更新的及时性，久而久之就失去了参考意义，反而还会加大团建之间的沟通成本。
而 Swagger 给我们提供了一个全新的维护 API 文档的方式，只要项目发布，就能够自动更新，而且可以
同步到线上，使用者只需要记住一个固定的网址，实时刷新就能访问到最新版本的API文档了。下面我总结一下
Swagger的主要优点：
1）代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的
时效性。
2）跨语言性，支持 40 多种语言。
3）提供交互式的UI，我们可以直接在文档页面调试 API，省去了准备复杂的调试参数的过程。
4）还可以将文档导入到自动化测试工具中，快速生成测试报告。
3、Swagger工作流程
Swagger接口生成工作流程：
1、系统启动时，扫描Swagger的配置类
2、在此类中指定来要扫描的包路径，找到在此包下及子包下标记@RestController注解的Controller类。还可
以通过以下这些注解来灵活配置一些参数。
比如：配置发送错误返回的信息 @ApiError ，配置一个或者多个请求参数，@ApiImplicitParam、@ApiImplicitParams等等。
3、根据Controller类中的Swagger注解生成接口文档，启动项目，访问项目虚拟路径/swagger-ui，查看生成
的文档内容。

Swagger 详解

Swagger 是一套用于 设计、构建、文档化和消费 RESTful API 的开源工具集，现已成为 OpenAPI 规范（OAS）的核心实现之一。它可以帮助开发者快速生成 API 文档、进行接口测试，并支持客户端代码自动生成。

---

1. Swagger 核心组件

(1) OpenAPI 规范（OAS）

• 定义 RESTful API 的标准格式（YAML/JSON）。
• 描述 API 的路径（Paths）、请求方法（HTTP Methods）、参数（Parameters）、响应（Responses）等。

(2) Swagger 工具生态

工具	作用
Swagger Editor	在线编辑器，用于编写和预览 OpenAPI 规范文档（YAML/JSON）。
Swagger UI	可视化 API 文档，支持在线测试接口。
Swagger Codegen	根据 API 规范生成客户端代码（如 Java、Python、TypeScript）。
Swagger Hub	企业级 API 设计、协作和托管平台（需付费）。

---

2. Spring Boot 集成 Swagger（SpringDoc OpenAPI）

由于 Swagger 2.x 已逐渐被 SpringDoc OpenAPI 3.x 取代（基于 OpenAPI 3.0），以下以 springdoc-openapi 为例：

(1) 添加依赖

<!-- SpringDoc OpenAPI (替代Swagger2) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

(2) 配置 Swagger UI

默认访问地址：http://localhost:8080/swagger-ui.html
可通过 application.yml 自定义：

springdoc:
  swagger-ui:
    path: /api-docs         # 修改Swagger UI路径
    tags-sorter: alpha      # 按字母排序标签
    operations-sorter: alpha # 按字母排序接口
  api-docs:
    path: /v3/api-docs      # OpenAPI JSON描述文件路径

(3) 常用注解

注解	作用	示例
@Tag	定义API分组（替代@Api）	@Tag(name = "用户管理", description = "用户相关接口")
@Operation	描述接口方法（替代@ApiOperation）	@Operation(summary = "创建用户", description = "根据User对象创建用户")
@Parameter	描述请求参数	@Parameter(name = "id", description = "用户ID", required = true)
@Schema	定义模型属性（替代@ApiModelProperty）	@Schema(description = "用户名", example = "张三")
@Hidden	隐藏接口/字段	@Hidden（不显示在Swagger UI中）

---

3. 代码示例

(1) Controller 示例

@RestController
@Tag(name = "用户管理", description = "用户相关API")
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户列表", description = "返回所有用户")
    @GetMapping
    public List<User> getUsers() {
        return userService.list();
    }

    @Operation(summary = "创建用户")
    @PostMapping
    public User createUser(@RequestBody @Valid User user) {
        return userService.save(user);
    }

    @Operation(summary = "根据ID查询用户")
    @Parameter(name = "id", description = "用户ID", required = true)
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getById(id);
    }
}

(2) DTO 模型示例

@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;

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

    @Schema(description = "邮箱", example = "user@example.com")
    private String email;
    // Getters & Setters
}

---

4. Swagger UI 功能

访问 http://localhost:8080/swagger-ui.html 后：

• 接口列表：按分组展示所有API。
• 在线测试：直接填写参数发起请求。
• 模型定义：查看请求/响应的数据结构。
• 下载OpenAPI JSON：通过 /v3/api-docs 获取标准描述文件。

---

5. 高级配置

(1) 安全认证（JWT/OAuth2）

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("BearerAuth", 
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")))
                .info(new Info().title("API文档").version("1.0"));
    }
}

(2) 分组显示多个模块

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("user")
            .pathsToMatch("/api/users/**")
            .build();
}

(3) 排除某些接口

springdoc:
  packages-to-exclude: com.example.internal.*

---

6. 常见问题

Q1: Swagger UI 不显示？

• 检查依赖是否正确引入。
• 确认路径是否被拦截（如Spring Security需放行/swagger-ui/**）。

Q2: 如何隐藏某些接口？

• 在方法上添加 @Hidden 注解。
• 使用 @Operation(hidden = true)。

Q3: 如何生成离线文档？

• 访问 /v3/api-docs 下载JSON文件，导入 Swagger Editor 生成HTML/PDF。

---

总结

• Swagger UI + OpenAPI 3.0 是当前主流API文档工具。
• SpringDoc 替代了旧的 springfox-swagger。
• 通过注解（@Tag、@Operation）定义接口细节。
• 支持在线测试、代码生成和权限集成。

适用于团队协作、前后端联调及自动化测试场景。