p1c2u/openapi-spec-validator

OpenAPI Spec Validator 镜像文档

镜像概述

OpenAPI Spec Validator 是一个用于验证OpenAPI规范文件合规性的工具，支持OpenAPI 2.0（又称Swagger）和OpenAPI 3.0版本。该工具原镜像p1c2u/openapi-spec-validator已迁移至pythonopenapi/openapi-spec-validator，旨在全面检查API规范文件是否符合官方定义的标准。

核心功能与特性

• 多版本支持：兼容OpenAPI 2.0（Swagger）和OpenAPI 3.0规范
• 多使用方式：支持通过Docker容器、命令行工具或Python库调用
• 灵活输入：可验证本地文件、标准输入流或URL中的规范文件
• 详细验证：提供完整的合规性检查，输出具体验证错误信息
• 轻量便捷：作为Docker镜像可快速部署，无需复杂环境配置

使用场景

• API开发过程中验证OpenAPI规范文件的正确性
• CI/CD流程集成，确保提交的API规范符合标准
• 自动化测试中检查API文档的有效性
• 批量验证多个OpenAPI规范文件的合规性

使用方法

Docker运行示例

通过Docker容器验证本地OpenAPI规范文件：

bash
# 验证本地openapi.yaml文件
docker run -v /path/to/local/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator /openapi.yaml

# 通过标准输入验证
cat /path/to/local/openapi.yaml | docker run -i --rm pythonopenapi/openapi-spec-validator -

命令行使用

在容器内直接使用命令行工具（需先进入容器）：

bash
# 进入容器
docker run -it --rm pythonopenapi/openapi-spec-validator /bin/bash

# 在容器内验证规范文件
openapi-spec-validator /path/to/openapi.yaml

Python库使用（补充说明）

该工具同时提供Python库，可在代码中集成验证功能：

python
# 验证OpenAPI 3.0规范
from openapi_spec_validator import validate_spec
from openapi_spec_validator.readers import read_from_filename

spec_dict, spec_url = read_from_filename('openapi.yaml')
validate_spec(spec_dict)  # 无异常则规范有效

# 验证OpenAPI 2.0规范
from openapi_spec_validator import validate_v2_spec
validate_v2_spec(spec_dict)

# 从URL验证规范
from openapi_spec_validator import validate_spec_url
validate_spec_url('http://example.com/openapi.json')

注意事项

• 确保挂载的本地文件路径正确，容器内路径与宿主机路径需对应
• 对于包含相对引用的规范文件，需通过spec_url参数指定基础路径
• 验证失败时会抛出OpenAPIValidationError并显示具体错误信息

相关项目

• https://github.com/p1c2u/openapi-core%EF%BC%9A%E6%8F%90%E4%BE%9BOpenAPI%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%92%8C%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%AB%AF%E6%94%AF%E6%8C%81%E7%9A%84Python%E5%BA%93
• https://github.com/p1c2u/openapi-schema-validator%EF%BC%9A%E9%AA%8C%E8%AF%81OpenAPI Schema规范的Python库

许可证

Apache License 2.0