本站支持搜索的镜像仓库：Docker Hub、gcr.io、ghcr.io、quay.io、k8s.gcr.io、registry.gcr.io、elastic.co、mcr.microsoft.com

openapitools/openapi-diff

用于比较两个OpenAPI规范（3.x版本）的工具，可将差异渲染为HTML、纯文本或Markdown文件。

1 收藏0 次下载activeopenapitools镜像

🚀轩辕镜像专业版更稳定💎一键安装 Docker 配置镜像源

中文简介版本下载

🚀轩辕镜像专业版更稳定💎一键安装 Docker 配置镜像源

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 拉取官方镜像：

docker pull openapitools/openapi-diff:latest

基本使用方法

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

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

参数说明

参数	描述
`--debug`	打印调试信息
`--error`	打印错误信息
`--fail-on-changed`	若 API 发生向后兼容的变更则退出码非 0
`--fail-on-incompatible`	仅当 API 变更破坏向后兼容性时退出码非 0
`-h,--help`	显示帮助信息
`--header <property=value>`	添加请求头用于授权（如 `Authorization=Bearer token`）
`--html <file>`	将差异导出为 HTML 文件（需挂载目录以保存文件）
`--info`	打印额外信息
`-l,--log <level>`	设置日志级别（TRACE、DEBUG、INFO、WARN、ERROR、OFF），默认：ERROR
`--markdown <file>`	将差异导出为 Markdown 文件（需挂载目录以保存文件）
`--off`	不打印任何信息
`--query <property=value>`	添加查询参数用于授权（如 `api_key=xxx`）
`--state`	仅输出差异状态：`no_changes`（无变更）、`incompatible`（不兼容）、`compatible`（兼容）
`--text <file>`	将差异导出为纯文本文件（需挂载目录以保存文件）
`--trace`	开启详细日志输出
`--version`	打印版本信息并退出
`--warn`	打印警告信息

构建本地镜像（可选）

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

# 克隆仓库（如需修改Dockerfile）
git clone [***]
cd openapi-diff

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

运行示例

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

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

导出差异为 HTML 文件：

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

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

# 若存在不兼容变更则失败（退出码非0）
docker run --rm openapitools/openapi-diff:latest \
  --fail-on-incompatible \
  [***] [***]

示例输出

CLI 文本输出

==========================================================================
==                            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 输出示例

### 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
...