From 61335a8cbd6e27503dac9fc50323f484b3572a7a Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 28 Oct 2023 12:11:22 +0300 Subject: [PATCH] update docs (#405) --- BREAKING-CHANGES.md | 22 +++++++++++----------- CHANGELOG.md | 23 +++++++++++++++++++++++ CUSTOMIZING-CHECKS.md | 3 +++ README.md | 2 +- 4 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 CHANGELOG.md diff --git a/BREAKING-CHANGES.md b/BREAKING-CHANGES.md index eba139ce..d06a5150 100644 --- a/BREAKING-CHANGES.md +++ b/BREAKING-CHANGES.md @@ -18,7 +18,7 @@ To exit with return code 1 even if only WARN-level breaking changes are found, a ### Output Formats The default output format is human-readable text. -You can specify the `--format` flag to output breaking-changes in json or yaml. +You can specify the `--format` flag to output breaking-changes in json, yaml, githubactions or junit formats. ### API Stability Levels When a new API is introduced, you may want to allow developers to change its behavior without triggering a breaking-change error. @@ -67,23 +67,23 @@ In most cases the `x-extensible-enum` is similar to enum values, except it allow If you don't use the `x-extensible-enum` in your OpenAPI specifications, nothing changes for you, but if you do, oasdiff will identify breaking changes related to `x-extensible-enum` parameters and properties. ### Optional Breaking-Changes Checks -You can use the `--include-checks` flag to include the following optional checks: -- response-non-success-status-removed -- api-operation-id-removed -- api-tag-removed -- api-schema-removed -- response-property-enum-value-removed -- response-mediatype-enum-value-removed -- request-body-enum-value-removed +You can use the `--include-checks` flag to include optional checks for breaking-changes. +Use the `oasdiff checks --required false` command to see the list of optional checks. For example: ``` oasdiff breaking data/openapi-test1.yaml data/openapi-test3.yaml --include-checks response-non-success-status-removed ``` +### Localization +To display changes in other languages use the `--lang` flag. +Currently English and Russian are supported. +[Please improve oasdiff by adding your own language](https://github.com/Tufin/oasdiff/issues/383). + ### Customizing Breaking-Changes Checks -If you encounter a change that isn't considered breaking by oasdiff and you would like to consider it as a breaking-change you may add an [optional breaking-changes check](#optional-breaking-changes-checks). -For more information, see [this guide](CUSTOMIZING-CHECKS.md) and this example of adding a custom check: https://github.com/Tufin/oasdiff/pull/208/files +If you encounter a change that isn't considered breaking by oasdiff you may: +1. Check if the change is already available as an [optional breaking-changes check](#optional-breaking-changes-checks). +2. Add a [custom check](CUSTOMIZING-CHECKS.md) ### Examples [Here are some examples of breaking and non-breaking changes that oasdiff supports](BREAKING-CHANGES-EXAMPLES.md). diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..b5984222 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +## Changelog +As your API evolves, it will undergo changes. Some of these changes may be "breaking" while others are not. +The changelog provides a list of all significant changes between two versions of the OpenAPI specification, including non-breaking changes. + +To generate the changelog between two specs run oasdiff with the `changelog` command: +``` +oasdiff changelog https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test3.yaml +``` + +The changes are categorized into three levels: +- `INFO` - Changes which are not breaking yet still important to know about +- `WARN` - Warnings are potential breaking changes which developers should be aware of, but cannot be confirmed programmatically +- `ERR` - Errors are definite breaking changes which should be avoided + +The changelog is actually an extension of the breaking changes output with additional `INFO`-level changes. +See [the breaking-changes documentation](BREAKING-CHANGES.md) for additional options that can be also be used with changelog command. + +### Output Formats +The default changelog format is human-readable text. +You can specify the `--format` flag to output the changelog as json or yaml. + +### Customizing the Changelog +If you encounter a change that isn't logged by oasdiff you may add a [custom check](CUSTOMIZING-CHECKS.md). diff --git a/CUSTOMIZING-CHECKS.md b/CUSTOMIZING-CHECKS.md index e27f4872..7bec4557 100644 --- a/CUSTOMIZING-CHECKS.md +++ b/CUSTOMIZING-CHECKS.md @@ -26,3 +26,6 @@ 3. Make sure that [BREAKING-CHANGES-EXAMPLES.md](BREAKING-CHANGES-EXAMPLES.md) was updated with your use-cases 4. If your check is optional, also add it to [this list of optional checks](https://github.com/Tufin/oasdiff#optional-breaking-changes-checks) +## Example +See this example of adding a custom check: https://github.com/Tufin/oasdiff/pull/208/files + diff --git a/README.md b/README.md index a30f3705..96072205 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ docker run --rm -t tufin/oasdiff changelog https://raw.githubusercontent.com/Tuf ## Features - Detect [breaking changes](BREAKING-CHANGES.md) +- Display a user-friendly [changelog](CHANGELOG.md) of all important API changes - OpenAPI diff in YAML, JSON, Text/Markdown or HTML -- Display a user-friendly [changelog](#openapi-changelog) of all important API changes - [Run from Docker](#openapi-diff-with-docker) - [Embed in your go program](#embedding-oasdiff-into-your-program) - OpenAPI diff of local files system or remote files over http/s