先厘清一个常见误区——Swagger不是“一个工具”，而是一套围绕OpenAPI规范的工具集。OpenAPI（原名Swagger Specification）是定义RESTful API的行业标准规范，比如规定文档必须包含info（文档基本信息）、paths（接口路径）、components（可复用组件）等核心结构；而Swagger是实现这个规范的工具套装：用Swagger Editor写规范文档、Swagger UI生成可交互网页、Swagger Codegen根据文档生成客户端/服务端代码。简单说：OpenAPI是“规则”，Swagger是“落地工具”。
从0到1写第一个OpenAPI文档
最推荐的入门方式是用Swagger Editor（在线版：editor.swagger.io）——左边写YAML（比JSON更易读），右边实时预览文档效果。我们以“用户登录API”为例，一步步写：
第一步：填文档基本信息（info）
info是文档的“身份证”，必须包含title（文档名称）、version（版本号），建议加description（文档说明）：
info:
title: 用户服务API文档
version: 1.0.0
description: 用于管理用户登录、注册、信息查询的RESTful接口
第二步：定义接口路径（paths）
paths是API的核心，每个路径对应一个接口。比如POST请求的/api/users/login接口，要写清楚请求方法、摘要、请求体、响应：
paths:
/api/users/login:
post:
summary: 用户登录（获取令牌）
description: 通过用户名和密码验证身份，成功返回JWT令牌
# 请求体（JSON格式）
requestBody:
required: true # 请求体必填
content:
application/json:
schema: # 请求参数模型
type: object
properties:
username:
type: string
example: "testuser_001" # 示例值（超有用！）
description: 用户名（长度6-20位）
password:
type: string
example: "Test@1234" # 示例值
description: 密码（包含大小写、数字、符号）
required: [username, password] # 必填参数
# 响应状态码
responses:
'200': # 成功响应
description: 登录成功
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: "登录成功"
data:
type: object
properties:
token:
type: string
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
'400': # 参数错误
description: 用户名或密码格式错误
'401': # 认证失败
description: 用户名或密码错误
写完这部分，右边预览区会自动显示接口的结构化文档——是不是已经有模有样了？
用Swagger UI生成可交互文档
写完的YAML文档，要让它“活”起来（能发送请求、看响应），就得用Swagger UI。两种方式快速实现：
方式1：用在线Swagger UI
打开Swagger UI在线版（swagger.io/tools/swagger-ui/），把Swagger Editor里的YAML内容复制到顶部输入框，点击“Explore”——立刻能看到可交互的文档：
– 点击接口右边的“Try it out”，输入示例的用户名（testuser_001）和密码（Test@1234）；
– 点击“Execute”，会模拟发送POST请求，下方显示响应结果（比如200状态码和token）。
这种方式不用部署，适合快速演示。
方式2：本地部署Swagger UI
如果要集成到项目里，下载Swagger UI的静态文件（GitHub：github.com/swagger-api/swagger-ui），做两步修改：
1. 把你的YAML文件（比如api-docs.yaml）放到dist目录下；
2. 修改dist/index.html中的url参数，指向你的YAML文件：
<script>
window.onload = function() {
const ui = SwaggerUIBundle({
url: "api-docs.yaml", // 你的YAML文件路径
dom_id: '#swagger-ui',
presets: [SwaggerUIBundle.presets.apis]
});
window.ui = ui;
};
</script>
然后用浏览器打开index.html，就能看到本地的可交互文档——和在线版效果一样，但更灵活。
进阶：让文档更简洁、更规范
当接口变多，重复内容会让文档变臃肿，这时候要学会复用组件（components）——把通用的模型、响应、参数定义在components里，然后用$ref引用。
示例1：复用响应模型
很多接口都会返回400（参数错误）、401（未授权）、500（服务器错误），我们把这些响应定义成通用组件：
components:
responses:
BadRequest: # 参数错误
description: 请求参数格式错误
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: "用户名长度需6-20位"
Unauthorized: # 未授权
description: 身份验证失败（令牌无效/过期）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: "令牌无效，请重新登录"
然后在接口中引用：
paths:
/api/users/login:
post:
responses:
'400':
$ref: '#/components/responses/BadRequest' # 引用通用响应
'401':
$ref: '#/components/responses/Unauthorized'
示例2：复用请求体模型
比如“用户注册”和“用户修改信息”都需要“用户基本信息”参数，我们定义成components/schemas：
components:
schemas:
UserBaseInfo: # 用户基本信息模型
type: object
properties:
username:
type: string
example: "testuser_001"
description: 用户名
email:
type: string
example: "test@example.com"
description: 邮箱
required: [username, email]
然后在接口中引用：
paths:
/api/users/register:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserBaseInfo' # 引用用户模型
这样不仅减少重复，还能保证所有接口的参数/响应格式一致——团队协作时超省心！
避坑：我踩过的3个常见错误
分享几个实战中常犯的错，帮你少走弯路：
- 漏填info的必填项：
info中的title和version是必须的，少了Swagger Editor会报红——我第一次写的时候漏了version，折腾了10分钟才找到问题。 - 用复杂嵌套结构：比如把
user.address.street直接写在schema里，会让文档很难读——尽量拆成components/schemas/Address，然后引用。 - 文档和代码不同步：很多团队“写完文档就不管了”，导致文档里的接口路径是
/api/login，实际代码是/api/v2/login——解决办法是自动生成文档：用OpenAPI Generator（github.com/OpenAPITools/openapi-generator），从代码注解（比如Spring Boot的@Operation、@ApiResponse）生成OpenAPI文档，每次代码提交自动更新文档。
最后：推荐的工具链
如果要做企业级API文档，推荐这样的工具链：
– 写文档：Swagger Editor（YAML）→ 保证符合OpenAPI规范；
– 展示文档：Swagger UI → 生成可交互页面；
– 自动更新：OpenAPI Generator → 从代码生成文档，避免同步问题；
– 团队协作：Confluence + Swagger UI截图 → 把文档整合到团队知识库。
原创文章，作者：，如若转载，请注明出处：https://zube.cn/archives/320