OpenAPIDiff

这是一个用于 OpenAPI 文档的 WIP 差异比较库。它可以生成两个 API 版本之间更改的层级列表。仅支持 OpenAPI v3.x。

要查看此库针对两个 YAML OpenAPI 文档运行并使用 markdown 选项时生成的示例，请查看 example 文件夹。

该库附带一个非常简单的可执行文件。如果您只想体验开箱即用的效果，最简单的选择是运行我在 Docker Hub 上托管的 Docker 镜像。

dockerized 可执行文件将需要您挂载一个或多个卷，其中包含您希望进行差异比较的 API 版本。假设您的 API 的旧版本和新版本位于当前工作目录中（分别命名为 old.json 和 new.json），一个简单的调用示例如下：

docker run --rm -v "$(pwd)/old.json:/api/old.json" -v "$(pwd)/new.json:/api/new.json" mattpolzin2/openapi-diff /api/old.json /api/new.json

您可以向 mattpolzin2/openapi-diff 传递 --markdown 标志以及两个 API 文档文件，以生成 markdown 格式的差异，而不是默认的纯文本差异。

有关所有选项，请参阅 --help。

作为库使用时，您首先需要从您的 manifest 文件中引用此软件包，或者通过 Xcode 将其拉取进来。

...
dependencies: [
  .package(url: "https://github.com/mattpolzin/OpenAPIDiff.git", .upToNextMinor(from: "0.7.0")),
  ...
],
...

然后您可以使用以下代码生成差异：

import OpenAPIKit
import OpenAPIDiff

let file1 = try Data(contentsOf: oldOpenAPIFile)
let file2 = try Data(contentsOf: newOpenAPIFile)

let api1 = try JSONDecoder().decode(OpenAPI.Document.self, from: file1)
let api2 = try JSONDecoder().decode(OpenAPI.Document.self, from: file2)

let comparison = api1.compare(to: api2)

let markdownDiff = comparison.markdownDescription
let plaintextDiff = comparison.description

默认情况下，您将获得所有未更改以及已更改的内容的条目。您可以轻松地省略相似之处，使用：

let differences = comparison.description { !$0.isSame }
let markdownDifferences = comparison.markdownDescription { !$0.isSame }

您正在生成的结构是 ApiDiff。如果您想以不同于 description() 和 markdownDescription() 方法的方式操作差异，您可以查看 ApiDiff.swift。

如果您需要比较 OAS 3.0 文档，您可以解码它，然后将其转换为 OAS 3.1 文档，以便进行语义差异比较。您可以在此项目的可执行目标中看到一个示例（请参阅 main.swift）。

库目标 (OpenAPIDiff) 和可执行目标 (openapi-diff) 都可以通过 swift build 或在 Xcode 11 中打开仓库根文件夹轻松构建。

可以使用包含的 Dockerfile 构建 Docker 镜像，命令如下：

docker build -t openapi-diff .