ARTICLE · 1266054
为什么大厂都重视 API 文档?深入理解 Swagger 的工作原理
大家好，我是小米，一个喜欢分享技术的31岁程序员大哥哥，前几天，公司来了一个新需求：开发一套电商后台管理系统。后端有几十个接口，前端需要根据接口开发页面，测试人员需要根据接口编写测试用例，第三方系统还要调用我们的 API。
项目负责人看着一堆 Java 代码，突然问了一个问题：“小米，咱们能不能把所有接口整理成一份文档？最好还能直接在页面上测试接口。”
我一听，这不就是 Swagger 擅长的事情吗？如果把后端服务比作一家餐厅，那么 API 就是餐厅的点餐窗口。前端是顾客，后端是厨房，而接口文档就是菜单。没有菜单，顾客不知道能点什么菜，也不知道每道菜多少钱，更不知道应该怎么点。
Swagger 就像一份可以交互的电子菜单，不仅能告诉大家有哪些接口、需要什么参数、返回什么结果，还能让开发人员直接在页面上发起请求。
今天，我们就从这个故事出发，聊聊 Java 社招面试中经常出现的问题：什么是 Swagger？如何在 Spring Boot 项目中实现它？
在传统开发模式中，后端开发人员写完接口，通常还需要手动编写接口文档，例如，我们开发了一个查询用户的接口：GET /users/{id}。
调用者需要知道几个问题：
这个接口的作用是什么？
路径参数 id 是什么类型？
请求成功后返回什么数据？
如果用户不存在，会返回什么错误？
调用接口需要携带哪些请求头？
如果这些信息依赖开发人员口头传达，或者分散在 Word、Excel 文档中，就很容易出现问题，后端修改了参数，文档却没有更新；前端按照旧文档开发，联调时才发现返回结构已经变化。结果就是大家互相确认、反复修改，开发效率大打折扣。
Swagger 的核心价值，就是帮助开发团队以统一的格式描述 HTTP API，并提供可视化的接口文档和交互式调试能力，它的主要组成部分如下。
这里需要注意一个容易被面试官追问的知识点：Swagger 和 OpenAPI 并不是完全相同的概念。
OpenAPI Specification，简称 OAS，是描述 HTTP API 的开放规范。Swagger 则是围绕这套规范发展起来的一系列工具的统称，现在很多项目采用 OpenAPI 规范描述接口，再使用 Swagger UI 展示文档。
另外，Swagger 也不是只能用于 Spring Boot。只要能够生成符合规范的 API 描述，就可以使用相应工具展示或处理文档。
说到这里，面试官可能会继续追问：“你在实际项目中怎么实现的？”
在 Spring Boot 项目中，常见做法是使用集成 OpenAPI 的工具自动生成接口描述，再通过 Swagger UI 提供可视化文档，如果项目采用 Spring Boot 3.x，可以考虑使用 springdoc-openapi，它能够读取 Spring MVC 控制器、请求参数、DTO 等信息，生成 OpenAPI 文档，并提供 Swagger UI 页面。
需要特别说明：springdoc-openapi 与传统的 Springfox Swagger 方案不是同一个项目，两者的配置方式和兼容性也存在差异。对于 Spring Boot 3.x 项目，通常优先考虑与其兼容的 springdoc-openapi 版本。
1. 添加 Maven 依赖
假设我们使用 Spring Boot 3.x 和 Spring MVC，可以添加以下依赖：
其中，${springdoc.version} 应替换为与你的 Spring Boot 版本兼容的 springdoc-openapi 版本，这里不直接写死某个版本，是因为 Spring Boot、Spring Framework 和 springdoc-openapi 的兼容关系会随版本变化，实际项目应该以官方兼容说明为准。
引入依赖后，在默认配置下，应用通常会提供以下两个地址：
如果项目配置了应用上下文路径、反向代理或自定义文档路径，实际访问地址可能有所不同，这两个地址分别对应不同的职责：一个负责输出机器可读的 API 描述，另一个负责把描述呈现给开发人员。
2. 编写 Spring Boot 接口
接下来，我们编写一个简单的用户查询接口。
用户 DTO 定义如下：
这里使用 Java record 简化数据对象的定义，需要项目使用支持 record 的 Java 版本。
即使没有编写专门的 Swagger 配置，只要相关依赖、Spring MVC 配置正常，springdoc-openapi 通常就能识别这个接口，并生成相应的 API 描述，它会尝试识别请求路径、HTTP 方法、路径参数和返回对象结构。
访问 Swagger UI 后，我们就可以看到类似这样的接口信息：
这就好比后端写好了一道菜，系统自动把菜名、配料和制作信息整理到菜单中，不过，自动生成并不意味着所有信息都准确无误。接口说明、复杂业务约束、特殊错误码等内容，仍然需要开发人员补充。
3. 使用注解完善接口文档
自动识别只能解决基础问题，假设前端看到一个用户查询接口，却不知道用户不存在时应该如何处理，也不知道 id 是否必须大于零，那么文档仍然不够完善。
这时可以使用 OpenAPI 注解补充信息，先为控制器添加标签：
然后为具体接口补充说明：
上面的注解主要来自 io.swagger.v3.oas.annotations 包。
需要注意，这段代码展示的是注解的使用方式。实际项目中，应将注解添加到前面的完整控制器中，而不是重复定义一个控制器类。
另外，声明了 404 响应并不代表应用就会自动返回 HTTP 404。我们仍然需要在业务代码中处理用户不存在的情况，并通过异常处理器等机制返回正确的状态码，文档描述的是接口契约，业务代码负责真正履行契约，两者必须保持一致。
可以，这也是 Swagger UI 很受开发人员欢迎的原因之一，打开接口文档后，选择一个接口，点击 Try it out，填写参数，再点击 Execute，就能直接发起 HTTP 请求。
例如，我们查询用户 1001：GET /users/1001，如果接口正常返回，页面就会展示响应状态码、响应头和响应正文，对于简单的 CRUD 接口，这种方式非常方便。开发人员不必频繁切换到 Postman，也可以快速验证参数和返回结果。
但这里有一个容易忽略的细节：Swagger UI 不是完整的自动化测试平台，它更适合接口探索、手工调试和开发联调。如果需要测试复杂业务流程、验证大量边界条件、执行回归测试，仍然需要结合 JUnit、MockMvc、RestAssured 等测试工具。
此外，接口能够在 Swagger UI 中被调用，并不意味着它一定可以被匿名访问。身份认证、权限校验、CSRF 防护、跨域策略等因素，仍然可能影响请求是否成功，如果接口需要 JWT Token，可以根据实际项目的认证方案配置 OpenAPI 的安全定义，让 Swagger UI 提供相应的授权输入能力。
开发环境有接口文档，大家都很开心；但到了生产环境，事情就没那么简单了，试想一下，如果你的电商系统暴露了所有内部接口，包括用户管理、订单查询、运营配置，甚至某些管理后台接口，那么攻击者可能通过文档快速了解系统的 API 结构。
这并不意味着 Swagger 本身存在漏洞，而是说明接口文档也属于需要管理的系统信息，实际项目中，可以从以下几个方面进行控制。
如果使用 Spring Boot，可以通过配置文件、条件装配或安全配置控制文档功能。
例如，可以按环境启用相关配置：
这段配置通常用于禁用 springdoc-openapi 的文档生成与 UI 功能。具体行为仍应结合所使用的版本进行验证。
但要记住：禁用 Swagger 文档，不等于保护了业务接口。即使文档完全关闭，攻击者仍然可能直接请求已知的 API 路径，真正的安全防线应该建立在身份认证、权限控制、输入校验、数据访问约束和网络访问策略之上，而不是寄希望于别人看不到接口地址。
聊到这里，我们再回到面试题本身，面试官问“什么是 Swagger？你用 Spring Boot 实现了它吗？”，通常不是只想听一句“加个依赖就行”。
他可能希望确认你是否理解 API 文档的生成机制，是否具备接口规范意识，以及能否考虑到真实项目中的兼容性和安全性,可以重点掌握以下知识点。
如果面试官进一步追问：“你们为什么不直接手写 Word 文档？”
你可以回答：Word 文档在接口数量较少时也能使用，但随着系统规模扩大，手工维护容易造成文档与实现不一致。基于代码生成 API 描述，可以减少重复劳动，并通过 OpenAPI 规范为接口调试、客户端代码生成和契约检查提供统一基础。
如果继续追问：“Swagger 能不能保证接口安全？”
正确答案是不能。Swagger 主要解决接口描述和调试问题，不能替代 Spring Security 等安全机制。接口的身份认证、授权校验和数据保护仍然需要由应用自身实现。
这几个问题能够答清楚，面试官就能看出你不仅会配置工具，也理解它在工程实践中的边界。
回顾今天的内容，我们可以把 Swagger 理解为一套帮助开发团队理解、展示和调试 API 的工具体系，而 OpenAPI 则是其中非常重要的接口描述规范。
在 Spring Boot 项目中，我们可以通过 springdoc-openapi 自动生成接口文档，再使用 Swagger UI 展示接口、填写参数并发起请求。配合适当的注解，还可以补充业务说明、参数示例和响应信息。
不过，真正有价值的接口文档，不是把所有 Controller 扫描一遍就结束了。它还需要准确描述业务契约，与实际返回结果保持一致，并且具备合理的访问控制。
对于 Java 社招面试来说，既要知道怎么集成，也要理解它为什么有用、如何维护，以及不能解决哪些问题，工具解决的是效率问题，规范解决的是协作问题，而安全设计解决的是系统能否可靠运行的问题。
如果你能把这三个层面结合起来讲清楚，那么面对 Swagger 相关面试题，就不只是会用一个工具，而是真正理解了它在后端工程中的价值。
我是小米，如果你喜欢我的文章，欢迎关注我的微信公众号“软件求生”，获取更多技术干货！
