openapitools/openapi-diff

OpenAPI-diff 镜像文档

概述

OpenAPI-diff 是一个用于比较两个 OpenAPI 规范（3.x 版本）的工具，支持将差异结果渲染为 HTML、纯文本或 Markdown 格式。该工具提供 Docker 镜像，方便用户快速部署和使用，无需手动配置依赖环境。适用于 API 版本变更管理、兼容性验证及文档差异分析等场景。

核心功能与特性

• 规范支持：兼容 OpenAPI 3.0 规范
• 深度比较：详细比较参数、响应、端点、HTTP 方法（GET、POST、PUT、DELETE 等）
• 授权支持：支持 Swagger API 授权机制
• 差异渲染：使用表达式语言渲染属性差异，支持 HTML、Markdown 和纯文本输出
• 兼容性检查：可检测 API 变更是否向后兼容，并提供状态输出（无变更、兼容变更、不兼容变更）

使用场景

• API 版本迭代时，检查接口变更是否破坏向后兼容性
• 生成 API 变更日志，用于文档更新或团队协作
• CI/CD 流程集成，自动检测不兼容变更并阻断构建
• 比较本地规范文件与远程服务器上的规范差异

快速开始

镜像获取

从 Docker Hub 拉取官方镜像：

bash
docker pull openapitools/openapi-diff:latest

基本使用方法

比较两个 OpenAPI 规范文件（本地文件或 HTTP URL）：

bash
docker run --rm openapitools/openapi-diff:latest <旧规范路径> <新规范路径>

参数说明

构建本地镜像（可选）

若需自定义镜像，可从源码构建：

bash
# 克隆仓库（如需修改Dockerfile）
git clone https://github.com/OpenAPITools/openapi-diff.git
cd openapi-diff

# 构建本地镜像
docker build -t local-openapi-diff .

运行示例

比较本地文件（需挂载包含规范文件的目录）：

bash
# 假设规范文件位于当前目录下的specs文件夹
docker run --rm -t \
  -v $(pwd)/specs:/specs:ro \
  openapitools/openapi-diff:latest /specs/old_api.yaml /specs/new_api.yaml

导出差异为 HTML 文件：

bash
docker run --rm -t \
  -v $(pwd)/specs:/specs:ro \
  -v $(pwd)/output:/output \
  openapitools/openapi-diff:latest \
  --html /output/diff.html \
  /specs/old_api.yaml /specs/new_api.yaml

检查兼容性并根据结果退出：

bash
# 若存在不兼容变更则失败（退出码非0）
docker run --rm openapitools/openapi-diff:latest \
  --fail-on-incompatible \
  https://old-api.com/spec.yaml https://new-api.com/spec.yaml

示例输出

CLI 文本输出

text
==========================================================================
==                            API CHANGE LOG                            ==
==========================================================================
                             Swagger Petstore                             
--------------------------------------------------------------------------
--                              What's New                              --
--------------------------------------------------------------------------
- GET    /pet/{petId}

--------------------------------------------------------------------------
--                            What's Deleted                            --
--------------------------------------------------------------------------
- POST   /pet/{petId}

--------------------------------------------------------------------------
--                          What's Deprecated                           --
--------------------------------------------------------------------------
- GET    /user/logout

--------------------------------------------------------------------------
--                            What's Changed                            --
--------------------------------------------------------------------------
- PUT    /pet
  Request:
        - Deleted application/xml
        - Changed application/json
          Schema: Backward compatible
...

Markdown 输出示例

markdown
### What's New
---
* `GET` /pet/{petId} Find pet by ID

### What's Deleted
---
* `POST` /pet/{petId} Updates a pet in the store with form data

### What's Changed
---
* `PUT` /pet Update an existing pet  
    Request
        Deleted application/xml
        Changed application/json
          Schema: Backward compatible
...

许可证

本镜像基于 Apache License 2.0 许可发布。

致谢

特别感谢以下项目和贡献者的启发与支持：

• https://github.com/Sayi/swagger-diff%EF%BC%88Sayi 开发）
• Adarsh Sharma (https://github.com/adarshsharma)
• Quentin Desramé (https://github.com/quen2404)