git.iko.soy/compaREST
on 6.7.8 help sign in
compaREST/README.md
309 lines 9.7 kB history raw
1# CompaREST
3[![Hackage](https://img.shields.io/hackage/v/comparest.svg?logo=haskell)](https://hackage.haskell.org/package/comparest)
4[![Stackage Lts](http://stackage.org/package/comparest/badge/lts)](http://stackage.org/lts/package/comparest)
5[![Stackage Nightly](http://stackage.org/package/comparest/badge/nightly)](http://stackage.org/nightly/package/comparest)
6[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8Compatibility checker for OpenAPI
9# Quick Start Guide
11## Your situation
13You 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.)
15You have recently released version 1.0 and things are going great: user are downloading your app, servers are processing requests.
17You describe your API in a file `api-1.0.0.yaml`:
19```yaml
20openapi: "3.0.0"
21info:
22 version: 1.0.0
23 title: Swagger Petstore
24 license:
25 name: MIT
26servers:
27 - url: https://example.com
28paths:
29 /pets:
30 get:
31 parameters:
32 - name: limit
33 in: query
34 required: false
35 schema:
36 type: integer
37 maximum: 20
38 responses:
39 "200":
40 description: ""
41 headers:
42 x-next:
43 schema:
44 type: string
45 content:
46 application/json:
47 schema:
48 $ref: "#/components/schemas/Pets"
49 post:
50 requestBody:
51 content:
52 application/json:
53 schema:
54 $ref: "#/components/schemas/Pet"
55 responses:
56 "201":
57 description: ""
58components:
59 schemas:
60 Pet:
61 type: object
62 required:
63 - id
64 - name
65 properties:
66 id:
67 type: integer
68 name:
69 type: string
70 minLength: 3
71 maxLength: 10
72 Pets:
73 type: array
74 items:
75 $ref: "#/components/schemas/Pet"
76```
78## Evolving your product
80Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.
82After a round of very intense programming you take a look at your new `api-1.1.0.yaml`:
84```yaml
85openapi: "3.0.0"
86info:
87 version: 1.1.0
88 title: Swagger Petstore
89 license:
90 name: MIT
91servers:
92 - url: https://example.com
93paths:
94 /pets:
95 get:
96 parameters:
97 - name: limit
98 in: query
99 required: false
100 schema:
101 type: integer
102 maximum: 30
103 responses:
104 "200":
105 description: ""
106 headers:
107 x-next:
108 schema:
109 type: string
110 content:
111 application/json:
112 schema:
113 $ref: "#/components/schemas/Pets"
114 post:
115 requestBody:
116 content:
117 application/json:
118 schema:
119 $ref: "#/components/schemas/Pet"
120 responses:
121 "201":
122 description: ""
123components:
124 schemas:
125 Pet:
126 type: object
127 required:
128 - id
129 - name
130 properties:
131 id:
132 type: integer
133 name:
134 type: string
135 minLength: 1
136 maxLength: 15
137 weight:
138 type: integer
139 Pets:
140 type: array
141 items:
142 $ref: "#/components/schemas/Pet"
143```
145Looking 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.
147## Assessing compatibility automatically
149Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.
151You can call it, passing the API your client will be aware of, and the API your server will serve like so:
153```bash
154docker 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.md
155```
157Running this command will output a file `report.md`, containing the compatibility report between the two APIs:
159> # Summary
161> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |
162> |------------------------------------------|-------------------------------------------------|-------------------------------|
163> | 5 | 6 | 0 |
165> # <span id="breaking-changes"></span>⚠️ Breaking changes
167> ## **GET** /pets
169> ### 📱⬅️ JSON Response – 200
171> #### `$[*].name(String)`
173> 1. Maximum length of the string changed from 10 to 15.
175> 2. Minimum length of the string changed from 3 to 1.
177> ## **POST** /pets
179> ### 📱➡️ JSON Request
181> #### `$.weight`
183> 1. Values are now limited to the following types:
185> - Number
187> 2. The property was previously implicitly described by the catch-all
188> "additional properties" case. It is now explicitly defined.
190> #### `$.weight(Number)`
192> Value is now a multiple of 1.0.
194> # <span id="non-breaking-changes"></span>🙆 Non-breaking changes
196> ## **GET** /pets
198> ### Parameter limit
200> #### JSON Schema
202> ##### `$(Number)`
204> Upper bound changed from 20.0 inclusive to 30.0 inclusive.
206> ### 📱⬅️ JSON Response – 200
208> #### `$[*].weight`
210> 1. Values are now limited to the following types:
212> - Number
214> 2. The property was previously implicitly described by the catch-all
215> "additional properties" case. It is now explicitly defined.
217> #### `$[*].weight(Number)`
219> Value is now a multiple of 1.0.
221> ## **POST** /pets
223> ### 📱➡️ JSON Request
225> #### `$.name(String)`
227> 1. Maximum length of the string changed from 10 to 15.
229> 2. Minimum length of the string changed from 3 to 1.
231You 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.
233## Additional formats
235You 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:
237```bash
238docker 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
239```
241# CLI docs
243```
244Usage: comparest (-c|--client ARG) (-s|--server ARG)
245 [--silent | --only-breaking | --all] [-o|--output ARG]
246 [--folding-block-quotes-style | --header-style]
247 [--signal-exit-code]
248 A tool to check compatibility between two OpenAPI specifications.
250 Usage examples
252 Compare files old.yaml with new.yaml and output the resulting report to
253 stdout:
255 comparest -c old.yaml -s new.yaml
257 Only output breaking changes and write a styled HTML report to file
258 report.html:
260 comparest -c old.yaml -s new.yaml --only-breaking -o report
262 Don't output anything, only fail if there are breaking changes:
264 comparest -c old.json -s new.json --silent
266 Write full report suitable for embedding into a GitHub comment to
267 report.html:
269 comparest -c old.json -s new.json --folding-block-quotes-style -o report.html
271Available options:
272 -h,--help Show this help text
273 -c,--client ARG A path to the file containing the specification that
274 will be used for the client of the API. Can be either
275 a YAML or JSON file.
276 -s,--server ARG A path to the file containing the specification that
277 will be used for the server of the API. Can be either
278 a YAML or JSON file.
279 --silent Silence all output. Only makes sense in combination
280 with --signal-exit-code.
281 --only-breaking Only report breaking changes in the output.
282 --all Report both incompatible and compatible changes.
283 Compatible changes will not trigger a failure exit
284 code.
285 -o,--output ARG The file path where the output should be written. If
286 the option is omitted the result will be written to
287 stdout.
289 The file extension is used to determine the type of
290 the output file.
292 Supports many formats such as markdown, html, rtf,
293 doc, txt, rst, and many more.
295 Leave out the extension to produce a self-contained
296 HTML report with styling.
297 --folding-block-quotes-style
298 The report tree is structured using summary/detail
299 HTML elements and indented using block quotes. This
300 style renders well on GitHub.Intended for HTML output
301 format. Markdown has rendering bugs on GitHub.
302 --header-style The report tree is structured using increasing levels
303 of headers.
304 --signal-exit-code Signal API compatibility with the exit code.
306 Exit with 0 if there are no breaking changes.
307 Exit with 1 if there are breaking changes.
308 Exit with 2 if could not determine compatibility.
309```