OAS-DIFF

OAS 3.1 Validation and Diff Tool

Dependencies

Git
Make
Go 1.18+

Build

Build
```
make build
```
Run
```
./build/oasdiff --version
```

Options

Validate

--base-file value, --f1 value    path of the base OAS 3.1 file
--help, -h                                   show help (default: false)

Diff

--base-file value, --f1 value    path of the base OAS 3.1 file
--second-file value, --f2 value  path of the second OAS 3.1 file
--type-filter value, --tf value  changelog Type filter (create/update/delete)
--output-html, --oh              save an html report (default: false)
--output-endpoint, --oe          endpoint based changelog output (default: false)
--loose, -l                      loosely diff, ignores global case sensitivity for strings comparisons and ignore headers that start with 'x-' and 'user-agent' (default: false)
--include-file-path, --ifp       whether or not to include the full file path from the diff changelog (default: false)
--ignore-descriptions, --id      whether or not to ignore descriptions when performing the diff (default: false)
--ignore-examples, --ie          whether or not to ignore examples when performing the diff (default: false)
--help, -h                       show help (default: false)

Examples

Version
```
./build/oasdiff -v
```
Available Commands
```
./build/oasdiff
```

Validate

./build/oasdiff validate --base-file examples/invalid.json
./build/oasdiff validate --f1 examples/invalid.json

Diff

./build/oasdiff diff --base-file examples/simple.json --second-file examples/simple2.json
./build/oasdiff diff --base-file examples/simple.json --second-file examples/simple2.json --loose
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter create
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter update
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter delete
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --ignore-descriptions
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --ignore-examples
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --loose --ignore-descriptions --ignore-examples
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-html
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-endpoint
./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-endpoint --output-html --type-filter update

Array Identifiers

Array identifiers are used only for arrays to compare arrays by a matching identifier and not based on order. If an identifiable element is found in both the from and to structures, they will be directly compared

Servers

URL         string             `json:"url,omitempty" diff:"url,identifier"`

Changelog Rules

Arrays

CREATE/DELETE -> Always the entire element
UPDATE -> Only the property, exception if the property is the identifier

Limitations

openapi field is not a part of the changelog, we only support OAS version 3.1, so any changes will cause a validation failure
jsonSchemaDialect field is not a part of the changelog, we only support OAS version 3.1 and it uses JSON Schema Validation Draft 2020-12
Specification Extensions are not supported (TODO)
parameters array of Reference Object are not supported (TODO)

up9inc/oas-diff