3、OpenAPI规范入门：OpenAPI简介、OpenAPI版本历史、YAML/JSON基础
好，咱们进入正题。这一章聊的是OpenAPI规范，说白了就是API的“身份证”。你想想看，前后端协作时，最怕什么？最怕接口文档跟实际代码对不上。我早年带团队时，就吃过这个亏——后端改了字段名，前端不知情，上线直接崩。从那以后，我强制团队所有项目必须先写OpenAPI描述文件，再写代码。
3.1 什么是OpenAPI规范
OpenAPI规范（原名Swagger规范）是一种用于描述HTTP API的接口描述语言。它用一套标准化的格式，把API的端点、请求参数、响应结构、认证方式等信息全部写清楚。机器能读，人也能读。
我个人习惯把OpenAPI文件看作“API的契约”。前端、后端、测试、甚至运维，都拿这份文件当唯一真相源。谁改接口，谁先改文件。改完文件再动代码，顺序不能乱。
核心价值：OpenAPI让API描述从“口头约定”变成“可执行的规范”。工具链可以基于它自动生成文档、Mock服务、客户端SDK、测试用例。
3.2 OpenAPI版本历史
OpenAPI规范经历过几次大版本迭代。我简单梳理一下，你心里有个谱。
| 版本 | 发布时间 | 关键变化 |
|---|---|---|
| Swagger 2.0 | 2014年 | 奠定基础结构，被广泛采用 |
| OpenAPI 3.0 | 2017年 | 引入components、oneOf/anyOf、callback、link等高级特性 |
| OpenAPI 3.1 | 2021年 | 全面对齐JSON Schema 2020-12，支持webhook、examples增强 |
嗯，这里要注意：虽然Swagger 2.0还在用，但我建议新项目直接上OpenAPI 3.0或3.1。3.1的JSON Schema兼容性更好，描述能力更强。我曾经把一个老项目的Swagger 2.0文件升级到3.1，光是重构definitions到components/schemas就花了两天。但升级完，工具链的报错少了一大半。
3.3 YAML与JSON基础
OpenAPI文件可以用YAML或JSON编写。我个人强烈推荐YAML。为什么？可读性更好，写起来也快。JSON的大括号和逗号太容易出错了。
3.3.1 YAML核心语法
YAML的规则其实很少，记住这几点就够了：
- 缩进：用空格，不要用Tab。层级关系靠缩进表示。
- 键值对：
key: value，冒号后面要加空格。 - 列表：用短横线
- item。 - 注释：用
#开头。
看个例子：
# 一个简单的用户信息
user:
id: 1001
name: 张三
roles:
- admin
- editor
active: true
metadata:
created_at: "2024-01-15"
这段YAML对应的JSON长这样：
{
"user": {
"id": 1001,
"name": "张三",
"roles": ["admin", "editor"],
"active": true,
"metadata": {
"created_at": "2024-01-15"
}
}
}
你对比一下，YAML是不是清爽多了？我刚开始学YAML时，总记不住冒号后面要空格。后来养成习惯：每次写完用在线校验器跑一遍，省得被缩进坑。
小技巧：写YAML时，字符串可以不加引号。但如果字符串里包含特殊字符（如冒号、井号、方括号），最好用双引号包起来，避免解析错误。
3.3.2 JSON核心语法
JSON大家应该都熟。不过我还是提几个容易踩的坑：
- 键名必须用双引号，单引号不行。
- 最后一个元素后面不能有逗号。
- 数字不能有前导零（比如
01会报错）。
我曾经帮同事排查过一个Bug：他写了个JSON文件，里面有个字段"version": "01.0.0"，结果解析出来变成了1.0。原因就是他把版本号写成了数字类型，前导零被吞了。所以，版本号、电话号码这类数据，一律用字符串。
3.4 OpenAPI文件的基本结构
一个标准的OpenAPI 3.0文件，骨架是这样的：
openapi: "3.0.3"
info:
title: 用户管理API
version: "1.0.0"
description: 提供用户注册、登录、信息查询功能
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: 获取用户列表
responses:
"200":
description: 成功返回用户列表
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
我来拆解一下每个部分：
- openapi：声明使用的OpenAPI版本号。
- info：API的元信息，标题、版本、描述。
- servers：API的基础URL。可以配多个，比如开发环境、生产环境。
- paths：核心部分，定义每个端点的请求方法和响应。
- components：可复用的数据模型、参数、响应等。用
$ref引用。
避坑指南：我曾经见过有人把components/schemas里的模型定义得特别大，一个User对象嵌套了七八层。结果生成的文档页面加载慢得像蜗牛。我的建议是：模型扁平化，嵌套不超过三层。如果确实需要深层结构，拆成多个小模型，用$ref组合。
3.5 本章知识体系
下面这张图帮你把本章的核心知识点串起来。你可以把它当作一个思维导图来看。
3.6 小结
这一章我们聊了OpenAPI是什么、版本怎么演变的、YAML和JSON怎么写、以及一个OpenAPI文件长什么样。说白了，OpenAPI就是API世界的通用语言。你掌握了它，前后端协作就不再是“你猜我猜”的游戏。
我个人建议：今天就去把你们项目里最常用的一个接口写成OpenAPI描述文件。不用多，一个端点就行。写完之后，用Swagger Editor打开看看，你会立刻感受到“契约驱动”带来的清晰感。