oasdiff

OpenAPI Diff

This Go module provides a diff utility for OpenAPI Spec 3.

Unique features vs. other diff tools

• This is a go module - it can be embedded into other Go programs
• Comprehensive diff: covers just about every aspect of OpenAPI Spec. See work in progress for some limitations.
• Deep diff into paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
• Patch support is currently being added - see work in progress

Build

git clone https://github.com/Tufin/oasdiff.git
cd oasdiff
go build

Running from the command-line

./oasdiff -base data/openapi-test1.yaml -revision data/openapi-test2.yaml

Running with Docker

Help

docker run --rm -t tufin/oasdiff -help

Comparing public files (text output):

docker run --rm -t tufin/oasdiff -base https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test3.yaml -format text

Comparing public files (yaml output):

docker run --rm -t tufin/oasdiff -base https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test3.yaml

Comparing public files (summary):

docker run --rm -t tufin/oasdiff -base https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test3.yaml -summary

Comparing local files (yaml output):

docker run --rm -t -v $(pwd)/data:/data:ro tufin/oasdiff -base /data/openapi-test1.yaml -revision /data/openapi-test3.yaml

Replace "$(pwd)/data" by the path that contains your files.

Output example - Text

New Endpoints

Deleted Endpoints

POST /register POST /subscribe

Modified Endpoints

GET /api/{domain}/{project}/badges/security-score

• New query param: filter
• New header param: user
• New cookie param: test
• Modified query param: image
  • Schema changed
    • Type changed from '' to 'string'
    • Format changed from '' to 'general string'
• Modified query param: token
  • Schema changed
• Response changed
  • New response: 201

GET /api/{domain}/{project}/install-command

• Modified path param: project
  • Schema changed
    • Deleted enum values: [test1]
• Response changed
  • Modified response: default

Output example - YAML

info:
  title:
    from: Tufin
    to: Tufin1
  contact:
    added: true
  license:
    added: true
  version:
    from: 1.0.0
    to: 1.0.1
paths:
  deleted:
    - /register
    - /subscribe
  modified:
    /api/{domain}/{project}/badges/security-score:
      operations:
        modified:
          GET:
            tags:
              deleted:
                - security
            parameters:
              modified:
                cookie:
                  test:
                    content:
                      mediaType: true
                header:
                  user:
                    schema:
                      schemaAdded: true
                    content:
                      mediaTypeDeleted: true
                query:
                  filter:
                    content:
                      schema:
                        required:
                          added:
                            - type
            responses:
              added:
                - default
              deleted:
                - "200"
              modified:
                "201":
                  content:
                    schema:
                      type:
                        from: string
                        to: object
      parameters:
        deleted:
          path:
            - domain
    /api/{domain}/{project}/install-command:
      operations:
        modified:
          GET:
            parameters:
              deleted:
                header:
                  - network-policies
            responses:
              modified:
                default:
                  description:
                    from: Tufin1
                    to: Tufin
                  headers:
                    deleted:
                      - X-RateLimit-Limit
            servers:
              added:
                - https://www.tufin.io/securecloud
endpoints:
  deleted:
    - method: POST
      path: /subscribe
    - method: POST
      path: /register
  modified:
    ? method: GET
      path: /api/{domain}/{project}/badges/security-score
    : tags:
        deleted:
          - security
      parameters:
        modified:
          cookie:
            test:
              content:
                mediaType: true
          header:
            user:
              schema:
                schemaAdded: true
              content:
                mediaTypeDeleted: true
          query:
            filter:
              content:
                schema:
                  required:
                    added:
                      - type
      responses:
        added:
          - default
        deleted:
          - "200"
        modified:
          "201":
            content:
              schema:
                type:
                  from: string
                  to: object
    ? method: GET
      path: /api/{domain}/{project}/install-command
    : parameters:
        deleted:
          header:
            - network-policies
      responses:
        modified:
          default:
            description:
              from: Tufin1
              to: Tufin
            headers:
              deleted:
                - X-RateLimit-Limit
      servers:
        added:
          - https://www.tufin.io/securecloud
security:
  deleted:
    - bearerAuth
servers:
  deleted:
    - tufin.com
tags:
  deleted:
    - security
    - reuven
externalDocs:
  deleted: true
components:
  schemas:
    added:
      - requests
    modified:
      network-policies:
        additionalPropertiesAllowed:
          from: true
          to: false
      rules:
        additionalPropertiesAllowed:
          from: null
          to: false
  parameters:
    deleted:
      header:
        - network-policies
  headers:
    deleted:
      - new
    modified:
      test:
        schema:
          additionalPropertiesAllowed:
            from: true
            to: false
      testc:
        content:
          schema:
            type:
              from: object
              to: string
  requestBodies:
    deleted:
      - reuven
  responses:
    added:
      - default
    deleted:
      - OK
  securitySchemes:
    deleted:
      - OAuth

Embedding into your Go program

diff.Get(&diff.Config{}, spec1, spec2)

See full example: main.go

Notes

1. oasdiff expects OpenAPI References to be resolved.
   References are normally resolved automatically when you load the spec. In other cases you can resolve refs using this function.

2. Use configuration to exclude certain types of changes:

   • Examples
   • Descriptions

3. Extensions are excluded by default. Use configuration to specify which ones to include.

4. Paths vs. Endpoints
   OpenAPI Specification has a hierarchial model of Paths and Operations.
   oasdiff respects this heirarchy and displays a hierarchial diff with path changes: added, deleted and modified, and within the later "modified" section, another set of operation changes: added, deleted and modified.
   For example:

    paths:
        deleted:
            - /register
            - /subscribe
        modified:
            /api/{domain}/{project}/badges/security-score:
                operations:
                    modified:
                        GET:

oasdiff also outputs an altrnate simplified view of "endpoints" which are a flattened combination of OpenAPI Paths and Operations, for example:

   endpoints:
        deleted:
            - method: POST
              path: /subscribe
            - method: POST
              path: /register
        modified:
            ?   method: GET
                path: /api/{domain}/{project}/badges/security-score
            :   tags:
                    deleted:
                        - security

Work in progress

1. While most aspects of OpenAPI Spec are already supported by this diff tool, one is still missing: server variables.
2. Patch support: currently supports Descriptions and a few fields in Schema

Credits

This project relies on the excellent implementation of OpenAPI 3.0 for Go: kin-openapi

Pull requests are welcome.