4、YAML与JSON基础：YAML语法入门、JSON语法对比、OpenAPI推荐格式与最佳实践

在 OpenAPI 接口契约设计中，描述文件的选择直接影响团队协作效率与工具链兼容性。YAML 与 JSON 是 OpenAPI 规范官方支持的两种序列化格式。本章将系统讲解 YAML 核心语法、与 JSON 的差异对比，并给出 OpenAPI 场景下的推荐格式与最佳实践。

4.1 YAML 语法入门

YAML（YAML Ain't Markup Language）是一种以缩进为核心的数据序列化格式，强调人类可读性。OpenAPI 3.x 规范中，YAML 是官方首选描述格式。

4.1.1 基础语法规则

4.1.2 核心数据结构

# 标量（Scalar）
name: 张三
age: 28
active: true
score: 95.5

# 列表（Sequence）
tags:
  - user
  - admin
  - manager

# 映射（Mapping）
address:
  city: 北京
  district: 海淀
  zip: "100000"

# 嵌套结构
user:
  id: 1001
  roles:
    - reader
    - writer
  profile:
    avatar: /images/avatar.png
    bio: 全栈工程师

4.1.3 多行字符串与锚点

# 保留换行（|）
description: |
  这是一个多行描述。
  第二行内容。
  第三行内容。

# 折叠换行（>）
summary: >
  这是一个折叠的
  长文本，最终会
  合并为一行。

# 锚点与引用（& / *）
base: &default
  timeout: 30
  retry: 3

service_a:
  <<: *default
  url: /api/a

service_b:
  <<: *default
  url: /api/b
  timeout: 60  # 覆盖默认值

4.2 JSON 语法对比

JSON（JavaScript Object Notation）是另一种广泛使用的数据格式，在 OpenAPI 工具链中兼容性最佳。以下从语法、可读性、工具支持三个维度进行对比。

4.2.1 语法差异对照表

4.2.2 同一数据两种格式对比

# YAML 版本
openapi: "3.0.3"
info:
  title: 用户服务
  version: "1.0.0"
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 成功

// JSON 版本
{
  "openapi": "3.0.3",
  "info": {
    "title": "用户服务",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "获取用户列表",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    }
  }
}

4.3 OpenAPI 推荐格式与最佳实践

基于社区实践与工具链兼容性，OpenAPI 官方及主流工具（Swagger Editor、Redoc、Stoplight）均推荐 YAML 作为首选描述格式。以下给出具体推荐策略。

4.3.1 格式选择决策矩阵

4.3.2 最佳实践清单

1. 统一缩进风格：整个项目强制使用 2 空格缩进，禁止混用 Tab 与空格。
2. 合理使用注释：在 description 字段中写详细说明，YAML 注释仅用于开发备注，不用于最终文档。
3. 避免深层嵌套：YAML 嵌套超过 4 层时，考虑使用 $ref 引用外部文件或组件。
4. 字符串加引号场景：包含冒号、#、特殊符号的字符串必须加双引号。
5. 布尔值统一：统一使用 true / false，避免使用 yes / no。
6. 文件拆分策略：超过 200 行的 OpenAPI 规范，按 paths/、components/、schemas/ 拆分多个 YAML 文件。
7. 使用 lint 工具：集成 spectral 或 vacuum 进行格式与规范校验。
8. JSON 作为交付格式：最终交付给 API 网关或生产环境时，将 YAML 编译为 JSON。

4.4 YAML 与 JSON 结构对比图

下图展示了同一 OpenAPI 片段在 YAML 与 JSON 中的结构差异，帮助直观理解两种格式的层级表达方式。

4.5 格式转换与工具链

在实际项目中，经常需要在 YAML 与 JSON 之间互转。以下列出常用工具与命令。