@@ -0,0 +1,51 @@
5+In cases where your OpenAPI spec can be generated from your code, it can be useful to see how a pull request changes your API. For this very purpose we have a Github Action.
7+### Generating the inputs
9+To use it you need to first get the old (before the pull request) and new (after the pull request) specs.
13+- To get the old spec you can:
14+ - Download from a public "production" server (if your api is public and you provide an OpenAPI spec)
15+ - Checkout the base commit of the pull request and generate is programmatically.
17+ You can checkout the base commit like so in Github Actions:
20+ git checkout $(git merge-base ${{ github.event.pull_request.head.sha }} ${{ github.event.pull_request.base.sha }})
22+- To get the new spec you can:
23+ - Build and run the spec generation for the head commit of the pull request
27+In our example we have already generated the two OpenAPI specs and placed them in the `old-openapi.yaml` and `new-openapi.yaml` files.
29+We can now run our action:
31+##### NOTE: will only work after public release
34+- uses: typeable/comparest
36+ old: old-openapi.yaml
37+ new: new-openapi.yaml
41+This will create a comment on the pull request displaying the changes (if there are any) similar to this:
43+
45+Consecutive runs of the action will update the comment instead of creating new ones. This will prevent the pile-up of compaREST comments and save you from distracting notifications.
47+## Integrating into something other than Github Actions
49+We have a dedicated implementation only for Github Actions. However, we provide a generic CLI which can be used to integrate compaREST into arbitrary workflows and CI systems.
51+You see an example of CLI usage in our [readme](../README.md#assessing-compatibility-automatically).