如何在JSON Schema中定义所有ErrorNumber/ErrorMessage组合用于生成文档

方案1：使用anyOf枚举所有合法错误组合（兼顾校验+文档生成） #

这是JSON Schema官方标准支持的实现方式，既可以实现接口返回值的合法性校验，也能被绝大多数JSON Schema文档生成工具自动识别，直接展示所有可用的错误码和对应消息。
修改后的参考代码如下：

{
    "type": "object",
    "required": [
        "ErrorNumber",
        "ErrorMessage"
    ],
    "properties": {
        "ErrorNumber": {
            "$id": "#root/ErrorNumber", 
            "type": "integer"
        },
        "ErrorMessage": {
            "$id": "#root/ErrorMessage", 
            "type": "string"
        }
    },
    // 在此处罗列所有合法的错误组合即可
    "anyOf": [
        {
            "properties": {
                "ErrorNumber": { "const": 10001 },
                "ErrorMessage": { "const": "参数缺失" }
            }
        },
        {
            "properties": {
                "ErrorNumber": { "const": 10002 },
                "ErrorMessage": { "const": "权限不足" }
            }
        },
        {
            "properties": {
                "ErrorNumber": { "const": 10003 },
                "ErrorMessage": { "const": "服务器内部错误" }
            }
        }
    ]
}

该方案优势：

• 校验能力强，只要返回的错误码和消息不匹配就会触发校验失败
• 主流文档生成工具（Redoc、Stoplight、Swagger UI等）都能自动识别并列出所有组合

方案2：仅需文档展示无需强校验，直接使用examples字段 #

如果你不需要做严格的逻辑校验，只是要在文档里展示所有错误组合，直接在对象层级补充examples数组即可，所有组合都放在数组中：
修改后的参考代码如下：

{
    "type": "object",
    "required": [
        "ErrorNumber",
        "ErrorMessage"
    ],
    "properties": {
        "ErrorNumber": {
            "$id": "#root/ErrorNumber", 
            "type": "integer"
        },
        "ErrorMessage": {
            "$id": "#root/ErrorMessage", 
            "type": "string"
        }
    },
    "examples": [
        {
            "ErrorNumber": 10001,
            "ErrorMessage": "参数缺失"
        },
        {
            "ErrorNumber": 10002,
            "ErrorMessage": "权限不足"
        },
        {
            "ErrorNumber": 10003,
            "ErrorMessage": "服务器内部错误"
        }
    ]
}

之前使用examples未生效大概率是因为只写了单个示例，没有把所有组合都放到examples数组中，换数组形式基本所有文档生成工具都可以识别。 #

方案3：单独枚举错误码+关联错误消息（适合错误码量较大的场景） #

如果错误码数量很多，写anyOf太繁琐，可以先单独枚举所有错误码，再用if/then逻辑绑定对应消息即可，该方式的校验能力和方案1一致，只是代码结构更简洁。

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