如何从Python argparse CLI生成完整JSON Schema

原有方案的核心问题是仅提取了参数解析后的默认值，完全没有利用ArgumentParser对象本身存储的参数元数据，自然会丢失帮助描述、必填属性、可选值范围等信息。不需要走parse_args流程，直接遍历parser内部存储的参数动作列表，就能拿到所有定义阶段的信息，自行组装JSON Schema即可。

argparse所有参数的定义信息都存在parser._actions列表中，每个action对象包含参数名、类型、默认值、帮助文本、必填标识、可选值范围、动作类型等全量元数据，配合简单的类型映射就能生成信息完整的Schema，不需要依赖genson从值反推类型。

实现参考代码：

import argparse
import json

parser = argparseParser(
    description="Some description", prog="myprog", usage="myprog [options]"
)
parser.add_argument(
    "-v",
    "--version",
    action="store_true",
    help="Print server version number and exit",
)
parser.add_argument(
    "-c",
    "--config",
    type=str,
    default=".fortls",
    help="Configuration options file (default file name: %(default)s)",
)
parser.add_argument(
    "input_file",
    type=str,
    help="Input file to process"
)

# 组装Schema基础结构
schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": parser.prog,
    "description": parser.description,
    "properties": {},
    "required": []
}

# argparse类型到JSON Schema类型映射
type_map = {
    str: "string",
    int: "integer",
    float: "number",
    bool: "boolean",
    list: "array"
}

for action in parser._actions:
    # 跳过自动生成的内置help动作
    if action.dest == "help":
        continue
    prop = {}
    # 匹配普通参数类型
    if action.type in type_map:
        prop["type"] = type_map[action.type]
    # 单独处理store_true/store_false类布尔参数
    if isinstance(action, (argparse._StoreTrueAction, argparse._StoreFalseAction)):
        prop["type"] = "boolean"
    # 写入默认值
    if action.default is not argparse.SUPPRESS:
        prop["default"] = action.default
    # 写入参数帮助描述
    if action.help:
        prop["description"] = action.help
    # 写入可选枚举值
    if action.choices:
        prop["enum"] = list(action.choices)
    # 标记必填参数
    if action.required:
        schema["required"].append(action.dest)
    
    schema["properties"][action.dest] = prop

print(json.dumps(schema, indent=2, ensure_ascii=False))

以上代码生成的Schema会自动包含参数描述、默认值、必填列表、可选枚举值等信息，覆盖绝大多数使用场景。如果需要支持更复杂的规则，比如nargs多值参数、互斥参数组，只要对应遍历parser的_mutually_exclusive_groups、_action_groups属性补充组装逻辑即可，这部分内部结构在argparse的版本迭代中非常稳定，几乎不会出现兼容性问题。

如果不想自行维护argparse到JSON Schema的转换逻辑，可以更换为原生支持模型导出的CLI框架，大幅减少开发量：

• Typer：基于Click封装，参数定义完全基于Python类型注解，可无缝对接Pydantic模型，一行代码即可导出包含完整校验规则、描述信息的JSON Schema，对嵌套结构、枚举类型、多值参数的支持非常完善，是目前这类需求的最优选择。
• Click：生态成熟度高，有成熟的配套工具可以直接从Click命令对象生成全量JSON Schema，支持自定义参数类型、帮助文本、必填项的自动导出，灵活度高。
• DocOpt：参数规则全部声明在标准化帮助文本中，结构天然规整，转换JSON Schema的逻辑非常简单，缺点是自定义扩展的灵活度低于前两个框架。

所有从参数解析结果反推Schema的方案都存在信息缺失的硬伤，参数值本身无法携带帮助说明、校验规则、参数间逻辑关系这类元信息，这类内容必须从CLI框架的参数定义对象中直接提取，才能保证生成的Schema完整可用。

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