如何从远程Swagger文档（WebSocket API）提取指定命令JSON结构

直接用awk/sed/grep这类文本工具处理JSON是下策——JSON是结构化数据，文本格式的微小变化（比如换行、缩进调整）都会导致脚本失效，完全适配不了Swagger版本迭代的场景，尤其你要在CI/CD里跑，稳定性优先。

最优方案是基于你已经在用的Python脚本，直接解析JSON结构，自动处理引用，提取目标定义：

具体实现步骤 #

1. 跳过写入本地文件的步骤（如果不需要保留原始JSON的话），直接把返回的JSON解析成Python字典
2. 递归解析Swagger中的$ref引用，合并allOf里的所有定义（包括BaseCommand的内容）
3. 提取你需要的必填字段或完整结构，生成需要的输出

示例代码 #

import requests
import json

def resolve_swagger_refs(definition, swagger_definitions):
    """递归解析Swagger定义中的$ref引用，合并allOf的内容"""
    if 'allOf' in definition:
        merged_def = {}
        for segment in definition['allOf']:
            if '$ref' in segment:
                # 提取引用的定义名称（比如从#/definitions/BaseCommand拿到BaseCommand）
                ref_name = segment['$ref'].split('/')[-1]
                merged_def.update(resolve_swagger_refs(swagger_definitions[ref_name], swagger_definitions))
            else:
                merged_def.update(segment)
        return merged_def
    elif '$ref' in definition:
        ref_name = definition['$ref'].split('/')[-1]
        return resolve_swagger_refs(swagger_definitions[ref_name], swagger_definitions)
    else:
        return definition

# 获取Swagger JSON数据
swagger_url = "https://<SWAGGER_URL>/swagger/v1/swagger.json"
response = requests.get(swagger_url)
swagger_data = response.json()

# 提取并解析UpdateCookieCommand的完整定义
target_command = "UpdateCookieCommand"
command_def = swagger_data['definitions'][target_command]
full_command_def = resolve_swagger_refs(command_def, swagger_data['definitions'])

# 提取必填字段
required_fields = full_command_def.get('required', [])
print(f"{target_command} 必填字段: {', '.join(required_fields)}")

# 保存解析后的完整定义到文件（可选，用于生成文档或命令）
with open(f"{target_command}_spec.json", 'w') as f:
    json.dump(full_command_def, f, indent=4)

这个方案的优势 #

• 稳定性高：基于JSON结构解析，不受格式排版变化影响，只要Swagger遵循OpenAPI规范，不管版本怎么变都能正常工作
• 自动处理引用：递归解析BaseCommand这类依赖定义，直接得到完整的命令结构，不用手动查找拼接
• 易维护扩展：要提取其他Command，只需要修改target_command变量即可，逻辑通用
• CI/CD友好：纯Python实现，只要流水线里有Python环境就能运行，无需依赖Linux特定命令

为什么不推荐文本处理工具 #

• 依赖JSON的文本格式，一旦Swagger生成的JSON缩进、换行改变，正则或awk脚本直接失效
• 无法处理$ref这类结构化引用，要手动写逻辑匹配对应行，复杂度高且容易出错
• 脚本可读性差，后续维护成本高

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