如何在Jupyter Notebook中正确读取并使用YAML格式OpenAPI规范数据

1. 解决「输出内容挤成一团」的问题 #

你现有代码已经成功将YAML文件加载为Python嵌套字典结构，直接print会把多层嵌套的字典压缩成单行，看起来杂乱。
可以用以下方式优化查看体验：

import yaml

# 必须将加载结果存为独立变量，否则后续无法调用数据
with open("openapi.yaml", 'r') as stream:
    try:
        openapi_content = yaml.safe_load(stream)
    except yaml.YAMLError as exc:
        print(exc)

# 方式1：美化打印整个结构，缩进清晰
from pprint import pprint
pprint(openapi_content)

# 方式2：Jupyter环境直接输入变量名`openapi_content`运行单元格，会自动渲染格式化字典

2. 按OpenAPI 3.0规范定向提取内容 #

OpenAPI规范的结构是固定的，不需要遍历整个大字典找内容，按固定层级路径取值即可：

核心字段访问路径 #

• API基础信息（标题、版本、描述）：openapi_content['info']
  示例：取API标题

  api_title = openapi_content['info']['title']
  print(api_title)
  

• 所有API请求路径列表：openapi_content['paths'] 为字典，键就是所有请求路径
  示例：列出全部可用路径

  all_api_paths = list(openapi_content['paths'].keys())
  print(all_api_paths)
  

• 指定路径的接口详情（参数、返回值、说明）：
  示例：提取/api路径下GET接口的所有参数信息

  # 定位到对应路径的配置块
  target_endpoint = openapi_content['paths']['/api']
  # 取GET方法的参数列表
  get_params = target_endpoint['get']['parameters']
  # 结构化输出参数信息
  for param in get_params:
      print(f"参数名：{param['name']} | 说明：{param.get('description', '无描述')} | 是否必填：{param['required']}")
  

3. 处理YAML中的$ref引用 #

你看到的$ref: '#/components/schemas/xxx'是OpenAPI的复用定义，对应内容存在根节点的components/schemas下，直接访问即可：

# 示例：获取名为data的schema定义
data_schema = openapi_content['components']['schemas']['data']
pprint(data_schema)

如果需要批量解析所有$ref，不要手动编写解析逻辑，直接使用openapi-core、openapi-spec-validator这类专门处理OpenAPI规范的库即可。

常见操作提示 #

• 取字段时报KeyError时，先pprint对应层级的字典，确认实际存在的键名，不要硬套示例路径
• 所有操作不要在with open()块内直接执行，先把加载结果存为独立变量，后续再做处理

内容的提问来源于stack exchange，提问作者maireaddata