docs/Integration_guide.md · typeable/compaREST

git.iko.soy/typeable/compaREST

typeable/compaREST/docs/Integration_guide.md

49 lines 1.8 kB history raw

1# Integration guide

3## Github Actions

5In 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

9To use it you need to first get the old (before the pull request) and new (after the pull request) specs.

11For example:

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:

19 ```bash

20 git checkout $(git merge-base ${{ github.event.pull_request.head.sha }} ${{ github.event.pull_request.base.sha }})

21 ```

22- To get the new spec you can:

23 - Build and run the spec generation for the head commit of the pull request

25### Run the action

27In our example we have already generated the two OpenAPI specs and placed them in the `old-openapi.yaml` and `new-openapi.yaml` files.

29We can now run our action:

31```yaml

32- uses: typeable/comparest

33 with:

34 old: old-openapi.yaml

35 new: new-openapi.yaml

36 project_name: TEST

37```

39This will create a check on the pull request displaying the changes (if there are any) similar to this:

41![](img/github-action-report.png)

43The check will show success when there are no breaking changes, and be neutral otherwise.

45## Integrating into something other than Github Actions

47We 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.

49You see an example of CLI usage in our [readme](../README.md#assessing-compatibility-automatically).