接口文档解析：Swagger/OpenAPI规范、YAML与JSON格式、从文档提取接口信息
做接口联调，第一步不是写代码，而是读文档。
我记得刚入行那会儿，拿到一份几十页的Word接口文档，翻到第三页就开始犯困。后来接触了Swagger，才明白——好的接口文档，应该是机器能读、人能看、工具能跑的。今天我们就来聊聊怎么把这份“说明书”吃透。
Swagger与OpenAPI：同一个东西的两个名字
先说个背景。Swagger是SmartBear公司搞的一套工具集，而OpenAPI是它背后的规范标准。说白了，Swagger是品牌名，OpenAPI是技术规范。就像“”和“即时通讯协议”的关系。
我个人习惯把OpenAPI规范看作接口的“身份证”。它用统一的方式描述：
- 接口地址（URL）
- 请求方法（GET/POST/PUT/DELETE）
- 参数结构（Query、Header、Body）
- 返回格式（状态码、响应体）
- 鉴权方式（API Key、OAuth）
核心要点：OpenAPI规范目前主流版本是3.0.x，相比2.0（即Swagger 2.0），3.0在请求体描述、回调、链接等方面更灵活。如果你看到项目还在用2.0，建议推动升级。
YAML vs JSON：你选哪个？
OpenAPI文档可以用两种格式编写：YAML和JSON。我自己的偏好是——写文档用YAML，传数据用JSON。
为什么会这样？你想想看，YAML的缩进结构天然适合人类阅读，写起来像在列提纲。而JSON的括号嵌套，看久了眼睛疼。
来看个对比：
# YAML 格式（推荐手写）
openapi: "3.0.0"
info:
title: 用户服务API
version: "1.0.0"
paths:
/users/{id}:
get:
summary: 获取用户信息
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: 成功返回用户对象// JSON 格式（适合程序解析）
{
"openapi": "3.0.0",
"info": {
"title": "用户服务API",
"version": "1.0.0"
},
"paths": {
"/users/{id}": {
"get": {
"summary": "获取用户信息",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": { "type": "integer" }
}
],
"responses": {
"200": { "description": "成功返回用户对象" }
}
}
}
}
}我的小技巧：用VS Code写YAML时，装个YAML插件，它会自动校验缩进。我曾经因为一个空格没对齐，排查了整整两个小时——嗯，从那以后我再也不敢手写YAML不校验了。
从文档里提取接口信息：三步走
拿到一份OpenAPI文档，怎么快速提取出我们需要的接口信息？我总结了三步：
- 找路径（paths）——所有接口都在这里，按模块分组
- 看方法（get/post/put/delete）——确定操作类型
- 读参数（parameters/requestBody）——搞清楚要传什么
举个例子，假设我们要调用“创建订单”接口。从文档里提取的信息应该是这样的：
| 字段 | 值 | 说明 |
|---|---|---|
| URL | /api/orders | 基础路径 + 资源路径 |
| 方法 | POST | 创建资源 |
| 请求头 | Content-Type: application/json | 必须携带 |
| 请求体 | { "userId": 123, "items": [...] } | 必填字段 |
| 成功响应 | 201 Created | 返回订单ID |
注意：有些文档会隐藏“默认值”和“枚举值”。比如某个字段类型是string，但实际只接受"pending"、"paid"、"cancelled"三种值。不仔细看枚举约束，联调时就会收到400错误。我曾经就因为这个，跟后端吵了一架——后来发现是我没看文档里的enum字段。
知识体系结构图
下面这张图，帮你理清本章的核心脉络：
实战：用工具自动提取接口信息
手动读文档太慢？我推荐用Swagger Editor或Swagger UI。把YAML/JSON文件拖进去，它会自动生成一个可交互的接口列表。你甚至可以直接在页面上点击“Try it out”来发送请求。
另外，如果你在写自动化测试脚本，可以用openapi-generator这个工具。它能把文档直接生成Python/Java/JavaScript的客户端代码。嗯，省去了手写HTTP请求的麻烦。
避坑指南：我曾经用openapi-generator生成过一套Python客户端，结果发现它把枚举值写成了字符串常量，而实际接口要求的是数字。所以——生成代码后，一定要对照文档手动校验一遍，别全信工具。
好了，关于接口文档解析，核心就是：看懂规范、选对格式、提取关键信息。下一章我们会聊怎么把这些信息用到实际的接口测试中去。
可可精品资料库