mirror of
https://github.com/typeable/compaREST.git
synced 2024-12-26 20:53:51 +03:00
Added docker image builder and quick start guide (#113)
* wip * Cleaned things up * Updated readme * updated command
This commit is contained in:
GitHub
parent
958a653cfc
commit
9aef830cf6
232
README.md
232
README.md
@ -6,7 +6,239 @@
|
||||
[](LICENSE)
|
||||
|
||||
Compatibility checker for OpenAPI
|
||||
# Quick Start Guide
|
||||
|
||||
## Your situation
|
||||
|
||||
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.)
|
||||
|
||||
You have recently released version 1.0 and things are going great: user are downloading your app, servers are processing requests.
|
||||
|
||||
You describe your API in a file `api-1.0.0.yaml`:
|
||||
|
||||
```yaml
|
||||
openapi: "3.0.0"
|
||||
info:
|
||||
version: 1.0.0
|
||||
title: Swagger Petstore
|
||||
license:
|
||||
name: MIT
|
||||
servers:
|
||||
- url: https://example.com
|
||||
paths:
|
||||
/pets:
|
||||
get:
|
||||
parameters:
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
maximum: 20
|
||||
responses:
|
||||
"200":
|
||||
description: ""
|
||||
headers:
|
||||
x-next:
|
||||
schema:
|
||||
type: string
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Pets"
|
||||
post:
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Pet"
|
||||
responses:
|
||||
"201":
|
||||
description: ""
|
||||
components:
|
||||
schemas:
|
||||
Pet:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
minLength: 3
|
||||
maxLength: 10
|
||||
Pets:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/Pet"
|
||||
```
|
||||
|
||||
## Evolving your product
|
||||
|
||||
Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.
|
||||
|
||||
After a round of very intense programming you take a look at your new `api-1.1.0.yaml`:
|
||||
|
||||
```yaml
|
||||
openapi: "3.0.0"
|
||||
info:
|
||||
version: 1.1.0
|
||||
title: Swagger Petstore
|
||||
license:
|
||||
name: MIT
|
||||
servers:
|
||||
- url: https://example.com
|
||||
paths:
|
||||
/pets:
|
||||
get:
|
||||
parameters:
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
maximum: 30
|
||||
responses:
|
||||
"200":
|
||||
description: ""
|
||||
headers:
|
||||
x-next:
|
||||
schema:
|
||||
type: string
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Pets"
|
||||
post:
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Pet"
|
||||
responses:
|
||||
"201":
|
||||
description: ""
|
||||
components:
|
||||
schemas:
|
||||
Pet:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 15
|
||||
weight:
|
||||
type: integer
|
||||
Pets:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/Pet"
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Assessing compatibility automatically
|
||||
|
||||
Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.
|
||||
|
||||
You can call it, passing the API your client will be aware of, and the API your server will serve like so:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Running this command will output a file `report.md`, containing the compatibility report between the two APIs:
|
||||
|
||||
> # Summary
|
||||
>
|
||||
> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |
|
||||
> |------------------------------------------|-------------------------------------------------|-------------------------------|
|
||||
> | 5 | 6 | 0 |
|
||||
>
|
||||
> # <span id="breaking-changes"></span>⚠️ Breaking changes
|
||||
>
|
||||
> ## **GET** /pets
|
||||
>
|
||||
> ### 📱⬅️ JSON Response – 200
|
||||
>
|
||||
> #### `$[*].name(String)`
|
||||
>
|
||||
> 1. Maximum length of the string changed from 10 to 15.
|
||||
>
|
||||
> 2. Minimum length of the string changed from 3 to 1.
|
||||
>
|
||||
> ## **POST** /pets
|
||||
>
|
||||
> ### 📱➡️ JSON Request
|
||||
>
|
||||
> #### `$.weight`
|
||||
>
|
||||
> 1. Values are now limited to the following types:
|
||||
>
|
||||
> - Number
|
||||
>
|
||||
> 2. The property was previously implicitly described by the catch-all
|
||||
> "additional properties" case. It is now explicitly defined.
|
||||
>
|
||||
> #### `$.weight(Number)`
|
||||
>
|
||||
> Value is now a multiple of 1.0.
|
||||
>
|
||||
> # <span id="non-breaking-changes"></span>🙆 Non-breaking changes
|
||||
>
|
||||
> ## **GET** /pets
|
||||
>
|
||||
> ### Parameter limit
|
||||
>
|
||||
> #### JSON Schema
|
||||
>
|
||||
> ##### `$(Number)`
|
||||
>
|
||||
> Upper bound changed from 20.0 inclusive to 30.0 inclusive.
|
||||
>
|
||||
> ### 📱⬅️ JSON Response – 200
|
||||
>
|
||||
> #### `$[*].weight`
|
||||
>
|
||||
> 1. Values are now limited to the following types:
|
||||
>
|
||||
> - Number
|
||||
>
|
||||
> 2. The property was previously implicitly described by the catch-all
|
||||
> "additional properties" case. It is now explicitly defined.
|
||||
>
|
||||
> #### `$[*].weight(Number)`
|
||||
>
|
||||
> Value is now a multiple of 1.0.
|
||||
>
|
||||
> ## **POST** /pets
|
||||
>
|
||||
> ### 📱➡️ JSON Request
|
||||
>
|
||||
> #### `$.name(String)`
|
||||
>
|
||||
> 1. Maximum length of the string changed from 10 to 15.
|
||||
>
|
||||
> 2. Minimum length of the string changed from 3 to 1.
|
||||
|
||||
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.
|
||||
|
||||
## Additional formats
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
# CLI docs
|
||||
|
||||
```
|
||||
Usage: openapi-diff (-c|--client ARG) (-s|--server ARG)
|
||||
|
||||
33
default.nix
Normal file
33
default.nix
Normal file
@ -0,0 +1,33 @@
|
||||
{ sources ? import ./nix/sources.nix
|
||||
, haskellNix ? import sources.haskellNix { inherit system; }
|
||||
, pkgs ? import haskellNix.sources.nixpkgs-2105 (haskellNix.nixpkgsArgs // {inherit system;})
|
||||
, system ? builtins.currentSystem
|
||||
}:
|
||||
let
|
||||
hsPkgs = pkgs.haskell-nix.stackProject {
|
||||
src = ./.;
|
||||
|
||||
modules = [
|
||||
{
|
||||
dontStrip = false;
|
||||
dontPatchELF = false;
|
||||
enableDeadCodeElimination = true;
|
||||
}
|
||||
];
|
||||
};
|
||||
|
||||
compaREST-static = pkgs.runCommand "compaREST-static" { } ''
|
||||
mkdir $out
|
||||
cp ${hsPkgs.projectCross.musl64.hsPkgs.openapi-diff.components.exes.openapi-diff + "/bin/openapi-diff"} $out/compaREST
|
||||
|
||||
${pkgs.nukeReferences}/bin/nuke-refs $out/compaREST
|
||||
'';
|
||||
compaREST = pkgs.dockerTools.buildImage {
|
||||
name = "compaREST";
|
||||
contents = [compaREST-static];
|
||||
config = {
|
||||
Entrypoint = [ "/compaREST" ];
|
||||
};
|
||||
};
|
||||
|
||||
in compaREST
|
||||
26
nix/sources.json
Normal file
26
nix/sources.json
Normal file
@ -0,0 +1,26 @@
|
||||
{
|
||||
"haskellNix": {
|
||||
"branch": "master",
|
||||
"description": "Alternative Haskell Infrastructure for Nixpkgs",
|
||||
"homepage": "https://input-output-hk.github.io/haskell.nix",
|
||||
"owner": "input-output-hk",
|
||||
"repo": "haskell.nix",
|
||||
"rev": "8c587f90d2986f87a8212c3469521db512bc7ed9",
|
||||
"sha256": "0a4mz47ccvl1nl2p08zbn33i1vmak4bjr4z6wqzzflnq90hg5a0s",
|
||||
"type": "tarball",
|
||||
"url": "https://github.com/input-output-hk/haskell.nix/archive/8c587f90d2986f87a8212c3469521db512bc7ed9.tar.gz",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
|
||||
},
|
||||
"niv": {
|
||||
"branch": "master",
|
||||
"description": "Easy dependency management for Nix projects",
|
||||
"homepage": "https://github.com/nmattia/niv",
|
||||
"owner": "nmattia",
|
||||
"repo": "niv",
|
||||
"rev": "e0ca65c81a2d7a4d82a189f1e23a48d59ad42070",
|
||||
"sha256": "1pq9nh1d8nn3xvbdny8fafzw87mj7gsmp6pxkdl65w2g18rmcmzx",
|
||||
"type": "tarball",
|
||||
"url": "https://github.com/nmattia/niv/archive/e0ca65c81a2d7a4d82a189f1e23a48d59ad42070.tar.gz",
|
||||
"url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
|
||||
}
|
||||
}
|
||||
174
nix/sources.nix
Normal file
174
nix/sources.nix
Normal file
@ -0,0 +1,174 @@
|
||||
# This file has been generated by Niv.
|
||||
|
||||
let
|
||||
|
||||
#
|
||||
# The fetchers. fetch_<type> fetches specs of type <type>.
|
||||
#
|
||||
|
||||
fetch_file = pkgs: name: spec:
|
||||
let
|
||||
name' = sanitizeName name + "-src";
|
||||
in
|
||||
if spec.builtin or true then
|
||||
builtins_fetchurl { inherit (spec) url sha256; name = name'; }
|
||||
else
|
||||
pkgs.fetchurl { inherit (spec) url sha256; name = name'; };
|
||||
|
||||
fetch_tarball = pkgs: name: spec:
|
||||
let
|
||||
name' = sanitizeName name + "-src";
|
||||
in
|
||||
if spec.builtin or true then
|
||||
builtins_fetchTarball { name = name'; inherit (spec) url sha256; }
|
||||
else
|
||||
pkgs.fetchzip { name = name'; inherit (spec) url sha256; };
|
||||
|
||||
fetch_git = name: spec:
|
||||
let
|
||||
ref =
|
||||
if spec ? ref then spec.ref else
|
||||
if spec ? branch then "refs/heads/${spec.branch}" else
|
||||
if spec ? tag then "refs/tags/${spec.tag}" else
|
||||
abort "In git source '${name}': Please specify `ref`, `tag` or `branch`!";
|
||||
in
|
||||
builtins.fetchGit { url = spec.repo; inherit (spec) rev; inherit ref; };
|
||||
|
||||
fetch_local = spec: spec.path;
|
||||
|
||||
fetch_builtin-tarball = name: throw
|
||||
''[${name}] The niv type "builtin-tarball" is deprecated. You should instead use `builtin = true`.
|
||||
$ niv modify ${name} -a type=tarball -a builtin=true'';
|
||||
|
||||
fetch_builtin-url = name: throw
|
||||
''[${name}] The niv type "builtin-url" will soon be deprecated. You should instead use `builtin = true`.
|
||||
$ niv modify ${name} -a type=file -a builtin=true'';
|
||||
|
||||
#
|
||||
# Various helpers
|
||||
#
|
||||
|
||||
# https://github.com/NixOS/nixpkgs/pull/83241/files#diff-c6f540a4f3bfa4b0e8b6bafd4cd54e8bR695
|
||||
sanitizeName = name:
|
||||
(
|
||||
concatMapStrings (s: if builtins.isList s then "-" else s)
|
||||
(
|
||||
builtins.split "[^[:alnum:]+._?=-]+"
|
||||
((x: builtins.elemAt (builtins.match "\\.*(.*)" x) 0) name)
|
||||
)
|
||||
);
|
||||
|
||||
# The set of packages used when specs are fetched using non-builtins.
|
||||
mkPkgs = sources: system:
|
||||
let
|
||||
sourcesNixpkgs =
|
||||
import (builtins_fetchTarball { inherit (sources.nixpkgs) url sha256; }) { inherit system; };
|
||||
hasNixpkgsPath = builtins.any (x: x.prefix == "nixpkgs") builtins.nixPath;
|
||||
hasThisAsNixpkgsPath = <nixpkgs> == ./.;
|
||||
in
|
||||
if builtins.hasAttr "nixpkgs" sources
|
||||
then sourcesNixpkgs
|
||||
else if hasNixpkgsPath && ! hasThisAsNixpkgsPath then
|
||||
import <nixpkgs> {}
|
||||
else
|
||||
abort
|
||||
''
|
||||
Please specify either <nixpkgs> (through -I or NIX_PATH=nixpkgs=...) or
|
||||
add a package called "nixpkgs" to your sources.json.
|
||||
'';
|
||||
|
||||
# The actual fetching function.
|
||||
fetch = pkgs: name: spec:
|
||||
|
||||
if ! builtins.hasAttr "type" spec then
|
||||
abort "ERROR: niv spec ${name} does not have a 'type' attribute"
|
||||
else if spec.type == "file" then fetch_file pkgs name spec
|
||||
else if spec.type == "tarball" then fetch_tarball pkgs name spec
|
||||
else if spec.type == "git" then fetch_git name spec
|
||||
else if spec.type == "local" then fetch_local spec
|
||||
else if spec.type == "builtin-tarball" then fetch_builtin-tarball name
|
||||
else if spec.type == "builtin-url" then fetch_builtin-url name
|
||||
else
|
||||
abort "ERROR: niv spec ${name} has unknown type ${builtins.toJSON spec.type}";
|
||||
|
||||
# If the environment variable NIV_OVERRIDE_${name} is set, then use
|
||||
# the path directly as opposed to the fetched source.
|
||||
replace = name: drv:
|
||||
let
|
||||
saneName = stringAsChars (c: if isNull (builtins.match "[a-zA-Z0-9]" c) then "_" else c) name;
|
||||
ersatz = builtins.getEnv "NIV_OVERRIDE_${saneName}";
|
||||
in
|
||||
if ersatz == "" then drv else
|
||||
# this turns the string into an actual Nix path (for both absolute and
|
||||
# relative paths)
|
||||
if builtins.substring 0 1 ersatz == "/" then /. + ersatz else /. + builtins.getEnv "PWD" + "/${ersatz}";
|
||||
|
||||
# Ports of functions for older nix versions
|
||||
|
||||
# a Nix version of mapAttrs if the built-in doesn't exist
|
||||
mapAttrs = builtins.mapAttrs or (
|
||||
f: set: with builtins;
|
||||
listToAttrs (map (attr: { name = attr; value = f attr set.${attr}; }) (attrNames set))
|
||||
);
|
||||
|
||||
# https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/lists.nix#L295
|
||||
range = first: last: if first > last then [] else builtins.genList (n: first + n) (last - first + 1);
|
||||
|
||||
# https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L257
|
||||
stringToCharacters = s: map (p: builtins.substring p 1 s) (range 0 (builtins.stringLength s - 1));
|
||||
|
||||
# https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L269
|
||||
stringAsChars = f: s: concatStrings (map f (stringToCharacters s));
|
||||
concatMapStrings = f: list: concatStrings (map f list);
|
||||
concatStrings = builtins.concatStringsSep "";
|
||||
|
||||
# https://github.com/NixOS/nixpkgs/blob/8a9f58a375c401b96da862d969f66429def1d118/lib/attrsets.nix#L331
|
||||
optionalAttrs = cond: as: if cond then as else {};
|
||||
|
||||
# fetchTarball version that is compatible between all the versions of Nix
|
||||
builtins_fetchTarball = { url, name ? null, sha256 }@attrs:
|
||||
let
|
||||
inherit (builtins) lessThan nixVersion fetchTarball;
|
||||
in
|
||||
if lessThan nixVersion "1.12" then
|
||||
fetchTarball ({ inherit url; } // (optionalAttrs (!isNull name) { inherit name; }))
|
||||
else
|
||||
fetchTarball attrs;
|
||||
|
||||
# fetchurl version that is compatible between all the versions of Nix
|
||||
builtins_fetchurl = { url, name ? null, sha256 }@attrs:
|
||||
let
|
||||
inherit (builtins) lessThan nixVersion fetchurl;
|
||||
in
|
||||
if lessThan nixVersion "1.12" then
|
||||
fetchurl ({ inherit url; } // (optionalAttrs (!isNull name) { inherit name; }))
|
||||
else
|
||||
fetchurl attrs;
|
||||
|
||||
# Create the final "sources" from the config
|
||||
mkSources = config:
|
||||
mapAttrs (
|
||||
name: spec:
|
||||
if builtins.hasAttr "outPath" spec
|
||||
then abort
|
||||
"The values in sources.json should not have an 'outPath' attribute"
|
||||
else
|
||||
spec // { outPath = replace name (fetch config.pkgs name spec); }
|
||||
) config.sources;
|
||||
|
||||
# The "config" used by the fetchers
|
||||
mkConfig =
|
||||
{ sourcesFile ? if builtins.pathExists ./sources.json then ./sources.json else null
|
||||
, sources ? if isNull sourcesFile then {} else builtins.fromJSON (builtins.readFile sourcesFile)
|
||||
, system ? builtins.currentSystem
|
||||
, pkgs ? mkPkgs sources system
|
||||
}: rec {
|
||||
# The sources, i.e. the attribute set of spec name to spec
|
||||
inherit sources;
|
||||
|
||||
# The "pkgs" (evaluated nixpkgs) to use for e.g. non-builtin fetchers
|
||||
inherit pkgs;
|
||||
};
|
||||
|
||||
in
|
||||
mkSources (mkConfig {}) // { __functor = _: settings: mkSources (mkConfig settings); }
|
||||
Loading…
Reference in New Issue
Block a user