@@ -1,14 +1,35 @@
1−# CompaREST
1+# compaREST
22
3−[](https://hackage.haskell.org/package/comparest)
4−[](http://stackage.org/lts/package/comparest)
3+[](https://hackage.haskell.org/package/comparest)
4+[](http://stackage.org/lts/package/comparest)
55[](http://stackage.org/nightly/package/comparest)
66[](LICENSE)
77
88Compatibility checker for OpenAPI
9−# Quick Start Guide
109
11−## Your situation
10+## Using compaREST in Github Actions
11+
12+Add the following step to your Github Actions workflow:
13+
14+```yaml
15+- uses: typeable/comparest
16+ if: ${{ github.event_name == 'pull_request' }}
17+ with:
18+ old: old-openapi.yaml
19+ new: new-openapi.yaml
20+```
21+
22+The `new` and `old` values should be paths to your OpenAPI specifications you want to compare.
23+
24+You will get something like this in your pull requests:
25+
26+
27+
28+For more detail please see our [integration guide](docs/Integration_guide.md).
29+
30+## An example
31+
32+### Your situation
1233
1334You are developing a very important server with a REST API. You have clients who use your API that you do not control. Say, you are also developing a mobile app that uses your API and you can't force someone to update to the latest version. (Or you prefer not to for UX reasons.)
1435
@@ -75,7 +96,7 @@ components:
7596 $ref: "#/components/schemas/Pet"
7697```
7798
78−## Evolving your product
99+### Evolving your product
79100
80101Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.
81102
@@ -144,7 +165,7 @@ components:
144165
145166Looking at the very large and complex API description, you grow more and more concerned that your old mobile app might stop working when you update the server. But the spec is too large and too complex to reasonably assess this manually.
146167
147−## Assessing compatibility automatically
168+### Assessing compatibility automatically
148169
149170Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.
150171
@@ -158,15 +179,15 @@ Running this command will output a file `report.md`, containing the compatibilit
158179
159180> # Summary
160181>
161−> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |
162−> |------------------------------------------|-------------------------------------------------|-------------------------------|
163−> | 5 | 6 | 0 |
182+> | [❌ Breaking changes](#breaking-changes) | [⚠️ Non-breaking changes](#non-breaking-changes) |
183+> |------------------------------------------|--------------------------------------------------|
184+> | 5 | 6 |
164185>
165−> # <span id="breaking-changes"></span>⚠️ Breaking changes
186+> # <span id="breaking-changes"></span>❌ Breaking changes
166187>
167188> ## **GET** /pets
168189>
169−> ### 📱⬅️ JSON Response – 200
190+> ### ⬅️☁️ JSON Response – 200
170191>
171192> #### `$[*].name(String)`
172193>
@@ -176,7 +197,7 @@ Running this command will output a file `report.md`, containing the compatibilit
176197>
177198> ## **POST** /pets
178199>
179−> ### 📱➡️ JSON Request
200+> ### ➡️☁️ JSON Request
180201>
181202> #### `$.weight`
182203>
@@ -191,7 +212,7 @@ Running this command will output a file `report.md`, containing the compatibilit
191212>
192213> Value is now a multiple of 1.0.
193214>
194−> # <span id="non-breaking-changes"></span>🙆 Non-breaking changes
215+> # <span id="non-breaking-changes"></span>⚠️ Non-breaking changes
195216>
196217> ## **GET** /pets
197218>
@@ -203,7 +224,7 @@ Running this command will output a file `report.md`, containing the compatibilit
203224>
204225> Upper bound changed from 20.0 inclusive to 30.0 inclusive.
205226>
206−> ### 📱⬅️ JSON Response – 200
227+> ### ⬅️☁️ JSON Response – 200
207228>
208229> #### `$[*].weight`
209230>
@@ -220,7 +241,7 @@ Running this command will output a file `report.md`, containing the compatibilit
220241>
221242> ## **POST** /pets
222243>
223−> ### 📱➡️ JSON Request
244+> ### ➡️☁️ JSON Request
224245>
225246> #### `$.name(String)`
226247>
@@ -230,7 +251,7 @@ Running this command will output a file `report.md`, containing the compatibilit
230251
231252You now know exactly in what situations and in what way your 1.0 version of the app will break if you deploy your 1.1 version of the server.
232253
233−## Additional formats
254+### Additional formats
234255
235256You can also produce a self-contained HTML report that you can open in your browser by simply omitting the file extension of the output file:
236257
@@ -238,7 +259,9 @@ You can also produce a self-contained HTML report that you can open in your brow
238259docker run --rm -v $(pwd):/data:rw typeable/comparest --client /data/api-1.0.0.yaml --server /data/api-1.1.0.yaml --output /data/report
239260```
240261
241−# CLI docs
262+## CLI docs
263+
264+For more detail please see our [user guide](docs/User_guide.md).
242265
243266```
244267Usage: comparest (-c|--client ARG) (-s|--server ARG)