docs/User_guide.md · typeable/compaREST

git.iko.soy/typeable/compaREST

on master help sign in

51 lines 2.1 kB history raw

1CompaREST User Guide

2====================

4Running the Tool

5----------------

6The tool accepts two OpenAPI 3.0.0 schema files in either JSON or YAML format.

7One is assumed to be the client version of the schema, and the other is the

8server version.

10The tool will look for changes between the schemas and detect whether they are

11breaking or not -- that is, if they prevent interoperability between the client

12and the server.

14Running:

15```

16comparest -c client.json -s server.json

17```

18will output a markdown report of the changes to the standard output.

20Compatibility status can be signaled via the exit code using

21`--signal-exit-code`. In case no report is needed, output can be suppressed with

22`--silent`. For example:

23```

24comparest -c client.json -s server.json --signal-exit-code --silent

25echo $?

26```

27If there were changes that the tool determined to be breaking, the exit code

28will be 1. If there were some changes the tool couldn't understand, the exit

29code will be 2. Otherwise if there were no breaking changes, the exit code will

30be 0.

32Controlling the Report

33----------------------

34By default the report includes breaking changes, as well as non-breaking:

35changes that would be considered breaking in the opposite direction. To only

36include breaking changes in the report use `--only-breaking`. The `--all` option

37restores the default behavior.

39The report can be formatted in a variety of ways supported by Pandoc. The `-o`

40option causes the report to be written to a file. The format of the file is

41determined from the extension. The supported extensions include:

42 - `.md` for markdown

43 - `.html` for an HTML snippet

44 - `.rst` for restructured text

45 - no extension for a self-contained HTML document with styles

47By default the report is split up into parts relating to different paths,

48requests, responses, etc, using headers of various levels. Alternatively, the

49report can use indended block-quotes to visualize the tree structure of the

50report. The header style is enabled with `--header-style`, and the block-quote

51style is enabled with `--folding-block-quotes-style`.