文章目录先说结论工作流程核心注解Swagger 生态演进SpringDoc 配置回答技巧与点评加分回答面试官点评个人网站后端写完接口前端问参数是啥返回啥——每次手动写文档太痛苦了。Swagger 通过注解自动生成 API 文档省去了这个麻烦。面试官问这题他想听的是你能不能讲清 Swagger 的工作流程、核心注解、以及和 OpenAPI 的关系先说结论维度说明是啥API 文档自动生成工具核心能力扫描注解 → 生成文档 → 提供在线调试 UI工作流程启动时扫描注解 → 生成 JSON/YAML → UI 渲染核心注解Api、ApiOperation、ApiParam生态Swagger 2 → OpenAPI 3 → SpringDoc在线调试Swagger UI 提供试一试功能|一句话记住Swagger就像自动说明书——代码写好了说明书自动出来还能在线试用工作流程1. 开发者在代码上加注解 RestController Api(tags 用户管理) public class UserController { ApiOperation(根据ID查询用户) GetMapping(/users/{id}) public User getUser(PathVariable Long id) { ... } } 2. 应用启动Swagger 扫描注解 Springfox/SpringDoc 自动扫描 RestController → 解析方法签名、注解、返回类型 → 生成 API 描述对象 3. 生成 API 文档JSON/YAML GET /v2/api-docs → 返回完整的 API 文档 JSON { swagger: 2.0, paths: { /users/{id}: { get: { summary: 根据ID查询用户, parameters: [{name: id, in: path}], responses: {200: {schema: {$ref: #/User}}} } } } } 4. Swagger UI 渲染文档 访问 /swagger-ui.html → 页面展示所有接口 → 每个接口可以Try it out在线调试核心注解注解作用示例Api描述 ControllerApi(tags “用户管理”)ApiOperation描述方法ApiOperation(“查询用户”)ApiParam描述参数ApiParam(“用户ID”)ApiModel描述实体类ApiModel(description “用户”)ApiModelProperty描述字段ApiModelProperty(“用户名”)ApiResponse描述响应ApiResponse(code404, message“用户不存在”)Api(tags用户管理)RestControllerRequestMapping(/users)publicclassUserController{ApiOperation(value创建用户,notes返回创建后的用户对象)PostMappingpublicUsercreateUser(ApiParam(value用户信息,requiredtrue)RequestBodyUserDTOdto){returnuserService.create(dto);}}ApiModel(description用户信息)publicclassUserDTO{ApiModelProperty(value用户名,requiredtrue,example张三)privateStringname;ApiModelProperty(value年龄,example25)privateIntegerage;}Swagger 生态演进版本说明Spring 集成Swagger 2原始版本Springfox已停更OpenAPI 3Swagger 2 的标准化版本SpringDoc推荐 SpringDoc基于 OpenAPI 3 的新实现原生支持 Spring BootSwagger 2 → OpenAPI 3 的变化Api→TagApiOperation→OperationApiParam→ParameterApiModel→Schema// OpenAPI 3 写法SpringDocTag(name用户管理)RestControllerpublicclassUserController{Operation(summary创建用户,description返回创建后的用户对象)PostMapping(/users)publicUsercreateUser(Parameter(description用户信息,requiredtrue)RequestBodyUserDTOdto){returnuserService.create(dto);}}SpringDoc 配置!-- Maven 依赖 --dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.3.0/version/dependency# application.ymlspringdoc:api-docs:path:/v3/api-docs# API 文档 JSON 端点swagger-ui:path:/swagger-ui.html# Swagger UI 端点packages-to-scan:com.example.controller# 扫描包零配置启动——加了依赖就自动生效访问/swagger-ui.html就能看到文档。Swagger 全景 工作流程 ├── 代码加注解 ├── 启动时扫描注解 ├── 生成JSON/YAML文档 └── Swagger UI渲染展示 核心注解 ├── Api/Tag —— 描述Controller ├── ApiOperation/Operation —— 描述方法 ├── ApiParam/Parameter —— 描述参数 └── ApiModel/Schema —— 描述实体 生态演进 ├── Swagger 2 → Springfox已停更 ├── OpenAPI 3 → SpringDoc推荐 └── 注解名变化功能更强 口诀注解标注API启动自动扫 JSON文档自动生UI页面在线调 Swagger2老版停更OpenAPI3新标准 SpringDoc零配置开箱即用最方便回答技巧与点评标准回答Swagger 是 API 文档自动生成工具。工作流程开发者在代码上加注解Api、ApiOperation 等→ 应用启动时自动扫描注解 → 生成 JSON/YAML 格式的 API 文档 → Swagger UI 渲染为可视化页面并支持在线调试。Swagger 2 已被标准化为 OpenAPI 3Spring 集成推荐用 SpringDoc替代停更的 Springfox零配置开箱即用。加分回答Springfox 为什么停更Springfox 长期不更新和 Spring Boot 2.6 有兼容性问题路径匹配策略变更社区转向 SpringDoc。SpringDoc 基于 OpenAPI 3持续维护原生支持 Spring Boot 3API 文档的进阶用法可以用 SecurityScheme 定义认证方式Bearer Token / OAuth用 Server 定义多环境地址用 ExampleObject 给参数示例。这些让文档更贴近真实使用场景API First 设计先写 OpenAPI YAML 定义接口再用工具swagger-codegen生成代码骨架。这种契约优先的方式比代码优先更适合前后端并行开发面试官点评这道题考的是你对API 规范化的认识。最忌讳的回答是只知道Api 注解——面试官想听的是工作流程扫描→生成→渲染和生态演进Swagger→OpenAPI→SpringDoc。能讲清注解到文档的完整链路再说出 SpringDoc 替代 Springfox 的原因就是高分回答。原文阅读内容有帮助点赞、收藏、关注三连评论区等你