Skip to content

README.md

Latest commit

 

History

History
152 lines (116 loc) · 3.97 KB

README.md

File metadata and controls

152 lines (116 loc) · 3.97 KB

OpenAPI Diff

Runs oasdiff changelog between two OpenAPI specs and outputs the differences as a nicely formatted markdown table.

Usage

- name: Diff OpenAPI Specs
  id: oasdiff
  uses: shapehq/actions/oasdiff@v1
  with:
    base: path/to/base-spec.yml
    head: path/to/head-spec.yml

- name: Show diff
  run: echo "${{ steps.oasdiff.outputs.diff }}"

With PR Comments

A common pattern is to show API changes in pull request comments:

name: OpenAPI Diff

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  oasdiff:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v4
        with:
          path: pr

      - name: Checkout base branch
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.base.ref }}
          path: base

      - name: Diff API
        id: diff
        uses: shapehq/actions/oasdiff@v1
        with:
          base: base/openapi.yml
          head: pr/openapi.yml

      - name: Build comment
        run: |
          cat > comment.md << 'EOF'
          ## OpenAPI Diff Report

          ${{ steps.diff.outputs.diff }}

          ---
          *Updated for commit ${{ github.event.pull_request.head.sha }}*
          EOF

      - name: Post PR comment
        uses: shapehq/actions/create-or-update-pr-comment@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          body-file: comment.md
          update-marker: oasdiff-report

Multiple API Specs

For projects with multiple OpenAPI specs:

- name: Diff Invoicing API
  id: diff-invoicing
  uses: shapehq/actions/oasdiff@v1
  with:
    base: base/invoicing-api.yml
    head: pr/invoicing-api.yml

- name: Diff Reporting API
  id: diff-reporting
  uses: shapehq/actions/oasdiff@v1
  with:
    base: base/reporting-api.yml
    head: pr/reporting-api.yml

- name: Build comment
  run: |
    cat > comment.md << 'EOF'
    ## OpenAPI Diff Report

    ### Invoicing API
    ${{ steps.diff-invoicing.outputs.diff }}

    ### Reporting API
    ${{ steps.diff-reporting.outputs.diff }}
    EOF

Inputs

Name Description Required Default
base Path to the base OpenAPI spec file Yes
head Path to the head OpenAPI spec file Yes
format Output format: table, text, html, or json No table

Outputs

Name Description
diff The formatted diff output
has-changes Whether there are changes (true/false)

Output Formats

  • table: Markdown table with color-coded severity indicators (default)
  • text: Plain text changelog from oasdiff
  • html: Full HTML with styling
  • json: Raw JSON for programmatic processing

Example Output

With the default table format, the output looks like this:

8 changes: 3 breaking, 2 warning, 3 info

Endpoint Change
🔴 GET /api/users removed the required property 'email' from the response
🔴 POST /api/users added the new required request property 'role'
🔴 DELETE /api/users/{id} endpoint removed
🟡 PUT /api/users/{id} removed the request property 'nickname'
🟡 PUT /api/users/{id} removed the request property 'avatar'
🟢 GET /api/users added the new optional query parameter 'filter'
🟢 POST /api/users added the optional property 'bio' to the response
🟢 components added the schema 'UserRole'
  • 🔴 Breaking changes - Will break existing clients
  • 🟡 Warnings - May affect some clients
  • 🟢 Info - Non-breaking additions or changes