on master help sign in
Added docker image builder and quick start guide (#113)
9aef830iko
README.md+232
@@ -6,7 +6,239 @@
6[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
7
8Compatibility checker for OpenAPI
8Compatibility checker for OpenAPI
9+# Quick Start Guide
9
10
11+## Your situation
12+
13+You 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.)
14+
15+You have recently released version 1.0 and things are going great: user are downloading your app, servers are processing requests.
16+
17+You describe your API in a file `api-1.0.0.yaml`:
18+
19+```yaml
20+openapi: "3.0.0"
21+info:
22+ version: 1.0.0
23+ title: Swagger Petstore
24+ license:
25+ name: MIT
26+servers:
27+ - url: https://example.com
28+paths:
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: ""
58+components:
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+```
77+
78+## Evolving your product
79+
80+Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.
81+
82+After a round of very intense programming you take a look at your new `api-1.1.0.yaml`:
83+
84+```yaml
85+openapi: "3.0.0"
86+info:
87+ version: 1.1.0
88+ title: Swagger Petstore
89+ license:
90+ name: MIT
91+servers:
92+ - url: https://example.com
93+paths:
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: ""
123+components:
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+```
144+
145+Looking 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.
146+
147+## Assessing compatibility automatically
148+
149+Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.
150+
151+You can call it, passing the API your client will be aware of, and the API your server will serve like so:
152+
153+```bash
154+docker 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+```
156+
157+Running this command will output a file `report.md`, containing the compatibility report between the two APIs:
158+
159+> # Summary
160+>
161+> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |
162+> |------------------------------------------|-------------------------------------------------|-------------------------------|
163+> | 5 | 6 | 0 |
164+>
165+> # <span id="breaking-changes"></span>⚠️ Breaking changes
166+>
167+> ## **GET** /pets
168+>
169+> ### 📱⬅️ JSON Response – 200
170+>
171+> #### `$[*].name(String)`
172+>
173+> 1. Maximum length of the string changed from 10 to 15.
174+>
175+> 2. Minimum length of the string changed from 3 to 1.
176+>
177+> ## **POST** /pets
178+>
179+> ### 📱➡️ JSON Request
180+>
181+> #### `$.weight`
182+>
183+> 1. Values are now limited to the following types:
184+>
185+> - Number
186+>
187+> 2. The property was previously implicitly described by the catch-all
188+> "additional properties" case. It is now explicitly defined.
189+>
190+> #### `$.weight(Number)`
191+>
192+> Value is now a multiple of 1.0.
193+>
194+> # <span id="non-breaking-changes"></span>🙆 Non-breaking changes
195+>
196+> ## **GET** /pets
197+>
198+> ### Parameter limit
199+>
200+> #### JSON Schema
201+>
202+> ##### `$(Number)`
203+>
204+> Upper bound changed from 20.0 inclusive to 30.0 inclusive.
205+>
206+> ### 📱⬅️ JSON Response – 200
207+>
208+> #### `$[*].weight`
209+>
210+> 1. Values are now limited to the following types:
211+>
212+> - Number
213+>
214+> 2. The property was previously implicitly described by the catch-all
215+> "additional properties" case. It is now explicitly defined.
216+>
217+> #### `$[*].weight(Number)`
218+>
219+> Value is now a multiple of 1.0.
220+>
221+> ## **POST** /pets
222+>
223+> ### 📱➡️ JSON Request
224+>
225+> #### `$.name(String)`
226+>
227+> 1. Maximum length of the string changed from 10 to 15.
228+>
229+> 2. Minimum length of the string changed from 3 to 1.
230+
231+You 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.
232+
233+## Additional formats
234+
235+You 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:
236+
237+```bash
238+docker 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+```
240+
241+# CLI docs
10
242
11```
243```
12Usage: openapi-diff (-c|--client ARG) (-s|--server ARG)
244Usage: openapi-diff (-c|--client ARG) (-s|--server ARG)
default.nixnew file+33
@@ -0,0 +1,33 @@
1+{ sources ? import ./nix/sources.nix
2+, haskellNix ? import sources.haskellNix { inherit system; }
3+, pkgs ? import haskellNix.sources.nixpkgs-2105 (haskellNix.nixpkgsArgs // {inherit system;})
4+, system ? builtins.currentSystem
5+}:
6+let
7+ hsPkgs = pkgs.haskell-nix.stackProject {
8+ src = ./.;
9+
10+ modules = [
11+ {
12+ dontStrip = false;
13+ dontPatchELF = false;
14+ enableDeadCodeElimination = true;
15+ }
16+ ];
17+ };
18+
19+ compaREST-static = pkgs.runCommand "compaREST-static" { } ''
20+ mkdir $out
21+ cp ${hsPkgs.projectCross.musl64.hsPkgs.openapi-diff.components.exes.openapi-diff + "/bin/openapi-diff"} $out/compaREST
22+
23+ ${pkgs.nukeReferences}/bin/nuke-refs $out/compaREST
24+ '';
25+ compaREST = pkgs.dockerTools.buildImage {
26+ name = "compaREST";
27+ contents = [compaREST-static];
28+ config = {
29+ Entrypoint = [ "/compaREST" ];
30+ };
31+ };
32+
33+in compaREST
nix/sources.jsonnew file+26
@@ -0,0 +1,26 @@
1+{
2+ "haskellNix": {
3+ "branch": "master",
4+ "description": "Alternative Haskell Infrastructure for Nixpkgs",
5+ "homepage": "https://input-output-hk.github.io/haskell.nix",
6+ "owner": "input-output-hk",
7+ "repo": "haskell.nix",
8+ "rev": "8c587f90d2986f87a8212c3469521db512bc7ed9",
9+ "sha256": "0a4mz47ccvl1nl2p08zbn33i1vmak4bjr4z6wqzzflnq90hg5a0s",
10+ "type": "tarball",
11+ "url": "https://github.com/input-output-hk/haskell.nix/archive/8c587f90d2986f87a8212c3469521db512bc7ed9.tar.gz",
12+ "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
13+ },
14+ "niv": {
15+ "branch": "master",
16+ "description": "Easy dependency management for Nix projects",
17+ "homepage": "https://github.com/nmattia/niv",
18+ "owner": "nmattia",
19+ "repo": "niv",
20+ "rev": "e0ca65c81a2d7a4d82a189f1e23a48d59ad42070",
21+ "sha256": "1pq9nh1d8nn3xvbdny8fafzw87mj7gsmp6pxkdl65w2g18rmcmzx",
22+ "type": "tarball",
23+ "url": "https://github.com/nmattia/niv/archive/e0ca65c81a2d7a4d82a189f1e23a48d59ad42070.tar.gz",
24+ "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
25+ }
26+}
nix/sources.nixnew file+174
@@ -0,0 +1,174 @@
1+# This file has been generated by Niv.
2+
3+let
4+
5+ #
6+ # The fetchers. fetch_<type> fetches specs of type <type>.
7+ #
8+
9+ fetch_file = pkgs: name: spec:
10+ let
11+ name' = sanitizeName name + "-src";
12+ in
13+ if spec.builtin or true then
14+ builtins_fetchurl { inherit (spec) url sha256; name = name'; }
15+ else
16+ pkgs.fetchurl { inherit (spec) url sha256; name = name'; };
17+
18+ fetch_tarball = pkgs: name: spec:
19+ let
20+ name' = sanitizeName name + "-src";
21+ in
22+ if spec.builtin or true then
23+ builtins_fetchTarball { name = name'; inherit (spec) url sha256; }
24+ else
25+ pkgs.fetchzip { name = name'; inherit (spec) url sha256; };
26+
27+ fetch_git = name: spec:
28+ let
29+ ref =
30+ if spec ? ref then spec.ref else
31+ if spec ? branch then "refs/heads/${spec.branch}" else
32+ if spec ? tag then "refs/tags/${spec.tag}" else
33+ abort "In git source '${name}': Please specify `ref`, `tag` or `branch`!";
34+ in
35+ builtins.fetchGit { url = spec.repo; inherit (spec) rev; inherit ref; };
36+
37+ fetch_local = spec: spec.path;
38+
39+ fetch_builtin-tarball = name: throw
40+ ''[${name}] The niv type "builtin-tarball" is deprecated. You should instead use `builtin = true`.
41+ $ niv modify ${name} -a type=tarball -a builtin=true'';
42+
43+ fetch_builtin-url = name: throw
44+ ''[${name}] The niv type "builtin-url" will soon be deprecated. You should instead use `builtin = true`.
45+ $ niv modify ${name} -a type=file -a builtin=true'';
46+
47+ #
48+ # Various helpers
49+ #
50+
51+ # https://github.com/NixOS/nixpkgs/pull/83241/files#diff-c6f540a4f3bfa4b0e8b6bafd4cd54e8bR695
52+ sanitizeName = name:
53+ (
54+ concatMapStrings (s: if builtins.isList s then "-" else s)
55+ (
56+ builtins.split "[^[:alnum:]+._?=-]+"
57+ ((x: builtins.elemAt (builtins.match "\\.*(.*)" x) 0) name)
58+ )
59+ );
60+
61+ # The set of packages used when specs are fetched using non-builtins.
62+ mkPkgs = sources: system:
63+ let
64+ sourcesNixpkgs =
65+ import (builtins_fetchTarball { inherit (sources.nixpkgs) url sha256; }) { inherit system; };
66+ hasNixpkgsPath = builtins.any (x: x.prefix == "nixpkgs") builtins.nixPath;
67+ hasThisAsNixpkgsPath = <nixpkgs> == ./.;
68+ in
69+ if builtins.hasAttr "nixpkgs" sources
70+ then sourcesNixpkgs
71+ else if hasNixpkgsPath && ! hasThisAsNixpkgsPath then
72+ import <nixpkgs> {}
73+ else
74+ abort
75+ ''
76+ Please specify either <nixpkgs> (through -I or NIX_PATH=nixpkgs=...) or
77+ add a package called "nixpkgs" to your sources.json.
78+ '';
79+
80+ # The actual fetching function.
81+ fetch = pkgs: name: spec:
82+
83+ if ! builtins.hasAttr "type" spec then
84+ abort "ERROR: niv spec ${name} does not have a 'type' attribute"
85+ else if spec.type == "file" then fetch_file pkgs name spec
86+ else if spec.type == "tarball" then fetch_tarball pkgs name spec
87+ else if spec.type == "git" then fetch_git name spec
88+ else if spec.type == "local" then fetch_local spec
89+ else if spec.type == "builtin-tarball" then fetch_builtin-tarball name
90+ else if spec.type == "builtin-url" then fetch_builtin-url name
91+ else
92+ abort "ERROR: niv spec ${name} has unknown type ${builtins.toJSON spec.type}";
93+
94+ # If the environment variable NIV_OVERRIDE_${name} is set, then use
95+ # the path directly as opposed to the fetched source.
96+ replace = name: drv:
97+ let
98+ saneName = stringAsChars (c: if isNull (builtins.match "[a-zA-Z0-9]" c) then "_" else c) name;
99+ ersatz = builtins.getEnv "NIV_OVERRIDE_${saneName}";
100+ in
101+ if ersatz == "" then drv else
102+ # this turns the string into an actual Nix path (for both absolute and
103+ # relative paths)
104+ if builtins.substring 0 1 ersatz == "/" then /. + ersatz else /. + builtins.getEnv "PWD" + "/${ersatz}";
105+
106+ # Ports of functions for older nix versions
107+
108+ # a Nix version of mapAttrs if the built-in doesn't exist
109+ mapAttrs = builtins.mapAttrs or (
110+ f: set: with builtins;
111+ listToAttrs (map (attr: { name = attr; value = f attr set.${attr}; }) (attrNames set))
112+ );
113+
114+ # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/lists.nix#L295
115+ range = first: last: if first > last then [] else builtins.genList (n: first + n) (last - first + 1);
116+
117+ # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L257
118+ stringToCharacters = s: map (p: builtins.substring p 1 s) (range 0 (builtins.stringLength s - 1));
119+
120+ # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L269
121+ stringAsChars = f: s: concatStrings (map f (stringToCharacters s));
122+ concatMapStrings = f: list: concatStrings (map f list);
123+ concatStrings = builtins.concatStringsSep "";
124+
125+ # https://github.com/NixOS/nixpkgs/blob/8a9f58a375c401b96da862d969f66429def1d118/lib/attrsets.nix#L331
126+ optionalAttrs = cond: as: if cond then as else {};
127+
128+ # fetchTarball version that is compatible between all the versions of Nix
129+ builtins_fetchTarball = { url, name ? null, sha256 }@attrs:
130+ let
131+ inherit (builtins) lessThan nixVersion fetchTarball;
132+ in
133+ if lessThan nixVersion "1.12" then
134+ fetchTarball ({ inherit url; } // (optionalAttrs (!isNull name) { inherit name; }))
135+ else
136+ fetchTarball attrs;
137+
138+ # fetchurl version that is compatible between all the versions of Nix
139+ builtins_fetchurl = { url, name ? null, sha256 }@attrs:
140+ let
141+ inherit (builtins) lessThan nixVersion fetchurl;
142+ in
143+ if lessThan nixVersion "1.12" then
144+ fetchurl ({ inherit url; } // (optionalAttrs (!isNull name) { inherit name; }))
145+ else
146+ fetchurl attrs;
147+
148+ # Create the final "sources" from the config
149+ mkSources = config:
150+ mapAttrs (
151+ name: spec:
152+ if builtins.hasAttr "outPath" spec
153+ then abort
154+ "The values in sources.json should not have an 'outPath' attribute"
155+ else
156+ spec // { outPath = replace name (fetch config.pkgs name spec); }
157+ ) config.sources;
158+
159+ # The "config" used by the fetchers
160+ mkConfig =
161+ { sourcesFile ? if builtins.pathExists ./sources.json then ./sources.json else null
162+ , sources ? if isNull sourcesFile then {} else builtins.fromJSON (builtins.readFile sourcesFile)
163+ , system ? builtins.currentSystem
164+ , pkgs ? mkPkgs sources system
165+ }: rec {
166+ # The sources, i.e. the attribute set of spec name to spec
167+ inherit sources;
168+
169+ # The "pkgs" (evaluated nixpkgs) to use for e.g. non-builtin fetchers
170+ inherit pkgs;
171+ };
172+
173+in
174+mkSources (mkConfig {}) // { __functor = _: settings: mkSources (mkConfig settings); }