Github 操作 - 比较并找出两个 OAS V3 文件之间的差异

Question

假设您有两个 OpenApi 规范 (OAS) V3 文件：

original-spec.yaml : 原始规格
modified-spec.yaml : 修改后的（具有增强/中断更改/等）
（https://gist.github.com/jy95/d7b53648eb756547eb67fd0db962f68d 上提供了两个文件的示例）

我想找到一个可以生成人类可读报告的 CLI 工具
（例如，我可以使用 PR Comment from File 在 PR 评论中上传它 )

我的要求如下：

无技术限制
（您可以自由使用任何编程语言库，只要它有效，包括在需要时使用 OAS 到 Swagger v2 转换器）
人类可读/可理解
（应该清楚，这样不了解OAS的人就不会迷路）
维持（不是强制性的，但更好）

目前我在网上找到了这些项目：
- openapi-diff
- quen2404/openapi-diff
- Azure/openapi-diff
- ...

（其他无疑存在：我留给你找一些/或帮我挑选一个足够好的...）

这里是 Github 工作流程的开始，可帮助您快速启动：

name: API Breaking Changes
# Everyone is happy with breaking changes ^^
on:
  pull_request:

jobs:
  build-report:
    needs: build-oas-artefacts
    runs-on: ubuntu-latest
    steps:
      - name: Download OAS file from SOURCE branch
        uses: actions/download-artifact@v1
        with:
          name: original-spec.yaml
      - name: Download OAS file from TARGET branch
        uses: actions/download-artifact@v1
        with:
          name: modified-spec.yaml

感谢帮助

Answer 1

我自己的回答：

    name: API Breaking Changes
    # Everyone is happy with breaking changes ^^
    on:
      pull_request:

    jobs:
      build-oas-artefacts:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/setup-node@v1
            with:
              node-version: '12.x'
          - name: Install required tools
            run: |
              npm install speccy -g
              npm install -g @openapitools/openapi-generator-cli@1.0.10-4.2.3
          - name: Set up env variables
            run:  |
              echo "::set-env name=CURRENT_BRANCH::$(echo ${{ github.head_ref }} | sed 's|.*/||')"
              echo "::set-env name=TARGET_BRANCH::$(echo ${{ github.base_ref }} | sed 's|.*/||')"
          - name: Clone repository in branch ${{ env.TARGET_BRANCH }}
            uses: actions/checkout@v2
            with:
              path: 'A'
              ref: ${{ github.base_ref }}
          - name: Clone repository in branch ${{ env.CURRENT_BRANCH }}
            uses: actions/checkout@v2
            with:
              path: 'B'
          - name: Check if OAS from ${{ env.CURRENT_BRANCH }} is valid
            run: |
              npx openapi-generator validate -i B/api.yml
          - name: Check if OAS from ${{ env.TARGET_BRANCH }} is valid
            run: |
              npx openapi-generator validate -i A/api.yml
          - name: Build OAS specifications
            run: |
              npx speccy resolve A/api.yml -o original-spec.yaml
              npx speccy resolve B/api.yml -o modified-spec.yaml
          - name: Upload single OAS file from ${{ env.TARGET_BRANCH }}
            uses: actions/upload-artifact@v1
            with:
              name: original-spec.yaml
              path: original-spec.yaml
          - name: Upload single OAS file from ${{ env.CURRENT_BRANCH }}
            uses: actions/upload-artifact@v1
            with:
              name: modified-spec.yaml
              path: modified-spec.yaml
      build-report:
        needs: build-oas-artefacts
        runs-on: ubuntu-latest
        steps:
          - uses: actions/setup-node@v1
            with:
              node-version: '13.x'
          - name: Install required tools
            run: |
              npm install openapi-diff -g
          - name: Download OAS file from SOURCE branch
            uses: actions/download-artifact@v1
            with:
              name: original-spec.yaml
              path: specs/
          - name: Download OAS file from TARGET branch
            uses: actions/download-artifact@v1
            with:
              name: modified-spec.yaml
              path: specs/
          - name: Set up env variables
            run:  |
              echo "::set-env name=ORIGIN_SPEC::$(echo "$(pwd)/specs/original-spec.yaml" )"
              echo "::set-env name=MODIFIED_SPEC::$(echo "$(pwd)/specs/modified-spec.yaml" )"
              echo "::set-env name=SPECS_LOG::$(echo "$(pwd)/breaking-changes.log" )"
              echo "::set-env name=JSON_DIFF_FILE::$(echo "$(pwd)/breaking-changes.json" )"
              echo "::set-env name=GH_COMMENT_FILE::$(echo "$(pwd)/Github-comment.md" )"
    # See : https://github.com/actions/download-artifact/issues/14
          - name: Restore permissions
            run: |
              chmod -R 777 ${{ env.ORIGIN_SPEC }}
              chmod -R 777 ${{ env.MODIFIED_SPEC }}
          - name: Generate report
            run: |
              openapi-diff ${{ env.ORIGIN_SPEC }} ${{ env.MODIFIED_SPEC }} | tee ${{ env.SPECS_LOG }}
              sed -n '1!p' ${{ env.SPECS_LOG }} > ${{ env.JSON_DIFF_FILE }}
          - uses: actions/upload-artifact@v1
            with:
              name: openapi-diff.json
              path: breaking-changes.json
          - name: Prepare comment on Github PR
            run: |
              sed -n '1p' ${{ env.SPECS_LOG }} >> ${{ env.GH_COMMENT_FILE }}
              printf "\n\n\`\`\`yaml\n" >> ${{ env.GH_COMMENT_FILE }}
              sed -n '1!p' ${{ env.SPECS_LOG }} >> ${{ env.GH_COMMENT_FILE }}
              printf "\n\`\`\`\n" >> ${{ env.GH_COMMENT_FILE }}
          - name: comment PR
            uses: machine-learning-apps/pr-comment@master
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
            with:
              path: Github-comment.md

Answer 2

我刚刚用 golang 写了这个 OAS diff 工具：https://github.com/Tufin/oasdiff

它输出 json 是这样的：

{
 "spec": {
  "paths": {
   "modified": {
    "/": {
     "operations": {
      "modified": {
       "POST": {
        "servers": {
         "added": [
          "https://app.amberflo.io/ingest-endpoint"
         ],
         "deleted": [
          "https://app.amberflo.io/ingest"
         ]
        }
       }
      }
     },
     "servers": {
      "added": [
       "https://app.amberflo.io/ingest-endpoint"
      ],
      "deleted": [
       "https://app.amberflo.io/ingest"
      ]
     }
    }
   }
  },
  "servers": {
   "added": [
    "https://app.amberflo.io/ingest-endpoint"
   ],
   "deleted": [
    "https://app.amberflo.io/ingest"
   ]
  }
 },
 "summary": {
  "diff": true,
  "components": {
   "paths": {
    "modified": 1
   },
   "servers": {
    "added": 1,
    "deleted": 1
   }
  }
 }
}

Github 操作 - 比较并找出两个 OAS V3 文件之间的差异

Github Actions - Compare and find differences between two OAS V3 files

automation

diff

openapi

github-actions

human-readable