codekie/openapi-examples-validator

openapi-examples-validator## 概述一个用于验证OpenAPI规范（支持v2和v3版本）中嵌入式JSON示例的工具，同时支持通过命令行参数验证外部示例文件，确保API文档中的示例数据与定义的schema一致。## 核心功能与特性-支持OpenAPI v2和v3版本规范

-验证嵌入式JSON示例：自动搜索OpenAPI规范中的响应示例并验证其与对应schema的一致性 -支持外部示例验证：通过命令行参数指定schema路径和示例文件路径进行验证 -批量验证能力：通过映射文件（JSON格式）批量指定多个schema与示例文件的对应关系 -多格式支持：兼容JSON和YAML格式的OpenAPI规范文件 -详细错误输出：以JSON格式输出验证错误，包含关键字、数据路径、schema路径等信息 -灵活配置：支持禁用额外属性检查、指定工作目录等高级选项## 使用场景-API文档维护：确保OpenAPI文档中的示例数据符合接口定义的schema -开发阶段验证：在API开发过程中快速检查示例是否符合设计规范 -CI/CD集成：作为自动化流程的一部分，在API文档更新时自动验证示例正确性 -外部示例管理：验证未嵌入在OpenAPI规范中的独立示例文件## 使用方法### Docker使用#### 基本命令格式shell docker run --rm -i \ --user=$(id -u) \ -v ${PWD}:/data \ codekie/openapi-examples-validator:latest \ [选项] /data/<openapi规范文件路径> #### 参数说明---rm：容器退出后自动删除 --i：保持标准输入打开 ---user=$(id -u)：使用当前用户ID运行，避免文件权限问题 --v ${PWD}:/data：将当前目录挂载到容器内的/data目录，用于访问OpenAPI规范文件和示例文件

示例：验证嵌入式示例```shell

docker run --rm -i
--user=$(id -u)
-v ${PWD}:/data
codekie/openapi-examples-validator:latest
/data/openapi-spec.yaml

|------|------|------|
| `-V` | `--version` | 输出版本号 |
| `-s` | `--schema-jsonpath <schema-jsonpath>` | 指定OpenAPI schema的JSON路径，用于验证外部示例文件 |
| `-e` | `--example-filepath <example-filepath>` | 外部示例文件的路径 |
| `-m` | `--mapping-filepath <mapping-filepath>` | 映射文件路径，JSON格式，键为schema路径，值为示例文件路径（支持数组和通配符，通配符参数需用引号包裹） |
| `-c` | `--cwd-to-mapping-file` | 将工作目录切换到映射文件所在目录，用于解析示例文件的相对路径 |
| `-n` | `--no-additional-properties` | 不允许示例中包含schema未定义的额外属性 |
| `-h` | `--help` | 输出帮助信息 |

### 使用示例#### 1. 验证外部示例指定schema路径和示例文件路径：```shell
docker run --rm -i \
    --user=$(id -u) \
    -v ${PWD}:/data \
    codekie/openapi-examples-validator:latest \
    -s $.paths./.get.responses.200.schema \
    -e /data/example.json \
    /data/openapi-spec.json
```#### 2. 使用映射文件批量验证创建映射文件`mapping.json`：```json
{
  "$.paths./.get.responses.200.schema": [
    "examples/valid1.json",
    "examples/valid2.json"
  ],
  "$.paths./.post.responses.400.schema": "examples/invalid.json"
}
```执行验证：```shell
docker run --rm -i \
    --user=$(id -u) \
    -v ${PWD}:/data \
    codekie/openapi-examples-validator:latest \
    -m /data/mapping.json \
    /data/openapi-spec.yaml
```### 错误输出示例验证错误将输出到`stderr`，格式为JSON数组：```json
[
    {
        "keyword": "type",
        "dataPath": ".versions[0].id",
        "schemaPath": "#/properties/versions/items/properties/id/type",
        "params": {
            "type": "string"
        },
        "message": "should be string",
        "examplePath": "/~1/get/responses/200/examples/application~1json"
    }
]
```## 注意事项-**格式支持限制**：`int32`、`float`、`double`格式支持`number`类型；`int64`格式仅支持`string`类型（受JavaScript数值精度限制）。
-**额外属性检查限制**：`--no-additional-properties`选项在使用`allOf`组合子模式时不生效，不会对使用组合关键字（如`allOf`、`anyOf`等）的子模式应用额外属性检查，此时会输出警告日志。