一、先搞懂：啥是OpenAPI？为啥要纠结格式？
咱们做后端开发的，经常要给前端、测试或者其他团队写接口说明——以前可能靠文档、靠口头传，后来就有了OpenAPI这么个规范，说白了就是用一种大家都认的“标准格式”写接口文档，能自动生成测试用例、接口调用代码，甚至直接生成可视化的接口页面，省了好多事。 但OpenAPI的规范文件，到底选YAML还是JSON？这俩都是“写配置、传数据”的格式，看着差不多，用起来差老多，接下来咱们掰开揉碎说。
二、YAML格式：像写作文似的配置，好懂不好控
YAML的全称是“YAML Ain’t Markup Language”（不是标记语言），核心特点就是“像人话”，没有一堆花括号、引号，写起来跟写作文似的。
2.1 YAML的优点：读着顺，写着快
YAML最大的好处就是“人类可读性拉满”，不用找半天花括号的对应关系，看一眼就知道哪块是接口、哪块是参数。 举个完整的OpenAPI YAML例子（技术栈：OpenAPI 3.0）：
# OpenAPI 3.0 完整示例：用户登录接口
openapi: 3.0.0
info:
title: 用户服务接口
version: 1.0.0
description: 提供用户注册、登录、获取信息的接口
servers:
- url: https://api.example.com/v1
description: 生产环境服务器
paths:
/user/login:
post:
summary: 用户登录接口
description: 接收用户名和密码，返回登录成功的Token
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: 用户名（手机号/邮箱）
password:
type: string
description: 密码（明文传输，需前端加密）
required:
- username
- password
responses:
'200':
description: 登录成功
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
msg:
type: string
example: 登录成功
data:
type: object
properties:
token:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
'400':
description: 参数错误或密码不正确
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
msg:
type: string
example: 用户名或密码错误
你看这个例子，所有层级都是靠“缩进”区分的，比如info下面的title、version，paths下面的/user/login，不用写花括号，看着特别清晰，哪怕是刚接触OpenAPI的新手，扫一眼也能大概知道这个接口是干啥的。
另外，YAML还支持写注释，就是上面例子里的#号内容，写配置的时候可以随时加说明，比如某个参数为啥要这么设，后期维护的时候一眼就能懂，不用翻之前的代码找逻辑。
2.2 YAML的缺点：缩进坑死人，兼容性差
YAML的核心问题就是“太依赖缩进”——你少打一个空格、多打一个空格，整个配置就废了。比如上面的例子里，paths下面的/user/login要缩进2格，要是你写成缩进4格，或者缩进1格，解析的时候直接报错，而且报错信息特别不友好，只会说“格式错误”，不会告诉你是哪行缩进错了，新手调这个能调一下午。
还有兼容性问题：不是所有工具都能完美支持YAML。比如有些老版本的接口生成工具、自动化测试工具，只认JSON，不认YAML；还有一些云平台的配置解析，对YAML的支持也有bug，比如某个字段的特殊字符解析错，导致配置不生效。
另外，YAML不适合存大文件。比如一个项目有上百个接口，写出来的YAML文件会特别长，找某个接口的时候，缩进层级多了，很容易看串行，而且版本控制的时候，改个小地方，可能整个文件的缩进都变，导致Git diff显示一堆修改，其实只有几行是真的改了。
三、JSON格式：机器认的配置，稳但丑
JSON的全称是“JavaScript Object Notation”（JavaScript对象表示法），本来是给JavaScript用的，后来成了通用的数据格式，核心特点就是“结构严谨，机器友好”。
3.1 JSON的优点：稳，兼容性拉满
JSON最大的好处就是“稳”——它的结构是固定的，用花括号{}、方括号[]、引号""来区分层级，没有缩进依赖，只要语法对，不管怎么排版，解析都不会错。
举个和上面YAML完全对应的OpenAPI JSON例子（技术栈：OpenAPI 3.0）：
{
"openapi": "3.0.0",
"info": {
"title": "用户服务接口",
"version": "1.0.0",
"description": "提供用户注册、登录、获取信息的接口"
},
"servers": [
{
"url": "https://api.example.com/v1",
"description": "生产环境服务器"
}
],
"paths": {
"/user/login": {
"post": {
"summary": "用户登录接口",
"description": "接收用户名和密码，返回登录成功的Token",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "用户名（手机号/邮箱）"
},
"password": {
"type": "string",
"description": "密码（明文传输，需前端加密）"
}
},
"required": ["username", "password"]
}
}
}
},
"responses": {
"200": {
"description": "登录成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 200
},
"msg": {
"type": "string",
"example": "登录成功"
},
"data": {
"type": "object",
"properties": {
"token": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}
}
}
}
}
}
}
},
"400": {
"description": "参数错误或密码不正确",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 400
},
"msg": {
"type": "string",
"example": "用户名或密码错误"
}
}
}
}
}
}
}
}
}
}
}
你看这个例子，所有层级都是靠花括号、方括号、引号区分的，哪怕你把所有内容都写成一行（只要语法对），解析也不会错。 另外，JSON的兼容性是真的拉满——所有的OpenAPI工具、接口生成工具、自动化测试工具、云平台配置，全支持JSON，不会出现“不认”的情况；而且JSON的语法错误信息特别清晰，比如少打一个引号，会告诉你“第12行第3列语法错误”，改起来特别方便。
3.2 JSON的缺点：看着乱，写着累
JSON最大的问题就是“人类可读性差”，一堆花括号、引号堆在一起，看着特别乱。比如上面的例子，paths下面的/user/login，要找对应的requestBody，得找半天花括号的对应关系，尤其是大文件，看着看着就串行；而且写JSON的时候，得时刻注意引号、逗号、花括号的配对，少打一个逗号、多打一个逗号，都得报错，写起来特别累，比如你加一个新的参数，得先加一个逗号，再写新的字段，新手经常忘加逗号，导致格式错误。
另外，JSON不支持写注释（注意：是标准JSON不支持，有些工具扩展的JSON支持注释，但不通用），写配置的时候没法加说明，后期维护的时候，看到某个字段，得翻之前的代码找逻辑，特别麻烦。
四、该怎么选？分场景来！
选YAML还是JSON，没有绝对的好坏，得看你的使用场景：
4.1 选YAML的场景
- 自己写OpenAPI文档，而且团队里都是熟悉YAML的人：比如你写的文档只给内部团队用，大家都知道YAML的缩进规则，那YAML读着顺，写着快，特别适合；
- 配置文件不复杂，接口数量少：比如一个小项目，只有几个接口，YAML写出来特别清晰，不用怕缩进坑；
- 需要加大量注释：比如配置里有很多特殊的逻辑，需要加注释说明，YAML的原生注释功能特别方便。
4.2 选JSON的场景
- 配置文件要给外部工具用：比如你要把OpenAPI文档导入到某个接口测试工具、代码生成工具，或者云平台的配置中心，选JSON准没错，不会出现兼容性问题；
- 配置文件复杂，接口数量多：比如一个大项目，有上百个接口，JSON的结构严谨，不会因为缩进问题出错，而且版本控制的时候，改个小地方，只会显示改的那几行，不会整个文件的缩进都变；
- 团队里有新手：新手对YAML的缩进规则不熟悉，容易出错，JSON的语法错误信息清晰，改起来方便，适合新手用。
4.3 注意事项
- 不要同时用两种格式：比如你写了YAML，又转成JSON，转的时候可能会丢注释、改格式，导致两个文件不一致，特别麻烦；
- 转格式的时候要注意：如果非要转，比如你写了YAML，要导入某个只认JSON的工具，一定要用专业的转格式工具（比如Swagger Editor、在线转格式工具），不要自己手动改，容易出错；
- 大文件尽量用JSON：大的YAML文件容易出现缩进问题，解析慢，JSON更适合大文件。
五、总结
YAML和JSON都是OpenAPI规范的合法格式，各有优缺点：YAML读着顺、写着快、支持注释，但容易因为缩进出错、兼容性差；JSON结构严谨、兼容性拉满、语法错误信息清晰，但看着乱、写着累、不支持注释。选的时候，根据自己的场景来：内部小项目、自己写文档、需要加注释，选YAML；外部工具用、大项目、团队有新手，选JSON。
评论
围绕“后端开发中OpenAPI规范文件格式选择YAML还是JSON，各有什么优缺点？”参与讨论