企业官网建设流程全解析

个人网站

后端写完接口，前端问"参数是啥？返回啥？"——每次手动写文档太痛苦了。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	描述 Controller	@Api(tags = “用户管理”)
@ApiOperation	描述方法	@ApiOperation(“查询用户”)
@ApiParam	描述参数	@ApiParam(“用户ID”)
@ApiModel	描述实体类	@ApiModel(description = “用户”)
@ApiModelProperty	描述字段	@ApiModelProperty(“用户名”)
@ApiResponse	描述响应	@ApiResponse(code=404, message=“用户不存在”)

@Api(tags="用户管理")@RestController@RequestMapping("/users")publicclassUserController{@ApiOperation(value="创建用户",notes="返回创建后的用户对象")@PostMappingpublicUsercreateUser(@ApiParam(value="用户信息",required=true)@RequestBodyUserDTOdto){returnuserService.create(dto);}}@ApiModel(description="用户信息")publicclassUserDTO{@ApiModelProperty(value="用户名",required=true,example="张三")privateStringname;@ApiModelProperty(value="年龄",example="25")privateIntegerage;}

Swagger 生态演进

版本	说明	Spring 集成
Swagger 2	原始版本	Springfox（已停更）
OpenAPI 3	Swagger 2 的标准化版本	SpringDoc（推荐） 👈
SpringDoc	基于 OpenAPI 3 的新实现	原生支持 Spring Boot

Swagger 2 → OpenAPI 3 的变化：

• @Api→@Tag
• @ApiOperation→@Operation
• @ApiParam→@Parameter
• @ApiModel→@Schema

// OpenAPI 3 写法（SpringDoc）@Tag(name="用户管理")@RestControllerpublicclassUserController{@Operation(summary="创建用户",description="返回创建后的用户对象")@PostMapping("/users")publicUsercreateUser(@Parameter(description="用户信息",required=true)@RequestBodyUserDTOdto){returnuserService.create(dto);}}

SpringDoc 配置

<!-- Maven 依赖 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.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 3，Spring 集成推荐用 SpringDoc（替代停更的 Springfox），零配置开箱即用。

加分回答

1. Springfox 为什么停更：Springfox 长期不更新，和 Spring Boot 2.6+ 有兼容性问题（路径匹配策略变更），社区转向 SpringDoc。SpringDoc 基于 OpenAPI 3，持续维护，原生支持 Spring Boot 3
2. API 文档的进阶用法：可以用 @SecurityScheme 定义认证方式（Bearer Token / OAuth），用 @Server 定义多环境地址，用 @ExampleObject 给参数示例。这些让文档更贴近真实使用场景
3. API First 设计：先写 OpenAPI YAML 定义接口，再用工具（swagger-codegen）生成代码骨架。这种"契约优先"的方式比"代码优先"更适合前后端并行开发

面试官点评

这道题考的是你对API 规范化的认识。最忌讳的回答是只知道"@Api 注解"——面试官想听的是工作流程（扫描→生成→渲染）和生态演进（Swagger→OpenAPI→SpringDoc）。能讲清注解到文档的完整链路，再说出 SpringDoc 替代 Springfox 的原因，就是高分回答。

原文阅读

---

内容有帮助？点赞、收藏、关注三连！评论区等你 💪