git.iko.soy/compaREST
on master help sign in
Better CLI docs (#106)
a501f6eiko
README.md+62
compare with master
unifiedsplit
@@ -6,3 +6,65 @@
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+
10+
11+```
12+Usage: openapi-diff (-c|--client ARG) (-s|--server ARG)
13+ [--silent | --only-breaking | --all] [-o|--output ARG]
14+ [--folding-block-quotes-style | --header-style]
15+ A tool to check compatibility between two OpenApi specifications.
16+
17+ Usage examples
18+
19+ Compare files old.yaml with new.yaml and output the resulting report to
20+ stdout:
21+
22+ openapi-diff -c old.yaml -s new.yaml
23+
24+ Only output breaking changes and write a styled HTML report to file
25+ report.html:
26+
27+ openapi-diff -c old.yaml -s new.yaml --only-breaking -o report
28+
29+ Don't output anything, only fail if there are breaking changes:
30+
31+ openapi-diff -c old.json -s new.json --silent
32+
33+ Write full report suitable for embedding into a GitHub comment to
34+ report.html:
35+
36+ openapi-diff -c old.json -s new.json --folding-block-quotes-style -o report.html
37+
38+Available options:
39+ -h,--help Show this help text
40+ -c,--client ARG A path to the file containing the specification that
41+ will be used for the client of the API. Can be either
42+ a YAML or JSON file.
43+ -s,--server ARG A path to the file containing the specification that
44+ will be used for the server of the API. Can be either
45+ a YAML or JSON file.
46+ --silent Silence all output.
47+ --only-breaking Only report breaking changes in the output.
48+ --all Report both incompatible and compatible changes.
49+ Compatible changes will not trigger a failure exit
50+ code.
51+ -o,--output ARG The file path where the output should be written. If
52+ the option is omitted the result will be written to
53+ stdout.
54+
55+ The file extension is used to determine the type of
56+ the output file.
57+
58+ Supports many formats such as markdown, html, rtf,
59+ doc, txt, rst, and many more.
60+
61+ Leave out the extension to produce a self-contained
62+ HTML report with styling.
63+ --folding-block-quotes-style
64+ The report tree is structured using summary/detail
65+ HTML elements and indented using block quotes. This
66+ style renders well on GitHub.Intended for HTML output
67+ format. Markdown has rendering bugs on GitHub.
68+ --header-style The report tree is structured using increasing levels
69+ of headers.
70+```
app/OpenAPI/Checker/Options.hs+32−8
@@ -9,6 +9,7 @@ where
9import GHC.Generics (Generic)
9import GHC.Generics (Generic)
10import OpenAPI.Checker.Report
10import OpenAPI.Checker.Report
11import Options.Applicative
11import Options.Applicative
12+import Options.Applicative.Help hiding (fullDesc)
12
13
13data Options = Options
14data Options = Options
14 { clientFile :: FilePath
15 { clientFile :: FilePath
@@ -28,7 +29,20 @@ optionsParserInfo =
28 (helper <*> optionsParser)
29 (helper <*> optionsParser)
29 (fullDesc
30 (fullDesc
30 <> header "openapi-diff"
31 <> header "openapi-diff"
32+ <> progDescDoc
33+ (Just $
31− <> progDesc "A tool to check compatibility between two OpenApi specifications.")
34+ par "A tool to check compatibility between two OpenApi specifications."
35+ <$$> hardline <> par "Usage examples" <> hardline
36+ <$$> indent
37+ 4
38+ (par "Compare files old.yaml with new.yaml and output the resulting report to stdout:"
39+ <$$> hardline <> indent 4 "openapi-diff -c old.yaml -s new.yaml"
40+ <$$> hardline <> par "Only output breaking changes and write a styled HTML report to file report.html:"
41+ <$$> hardline <> indent 4 "openapi-diff -c old.yaml -s new.yaml --only-breaking -o report"
42+ <$$> hardline <> par "Don't output anything, only fail if there are breaking changes:"
43+ <$$> hardline <> indent 4 "openapi-diff -c old.json -s new.json --silent"
44+ <$$> hardline <> par "Write full report suitable for embedding into a GitHub comment to report.html:"
45+ <$$> hardline <> indent 4 "openapi-diff -c old.json -s new.json --folding-block-quotes-style -o report.html")))
32
46
33optionsParser :: Parser Options
47optionsParser :: Parser Options
34optionsParser =
48optionsParser =
@@ -36,19 +50,23 @@ optionsParser =
36 <$> strOption
50 <$> strOption
37 (short 'c'
51 (short 'c'
38 <> long "client"
52 <> long "client"
53+ <> help
54+ "A path to the file containing the specification that will be \
39− <> help "The specification that will be used for the client of the API.")
55+ \used for the client of the API. Can be either a YAML or JSON file.")
40 <*> strOption
56 <*> strOption
41 (short 's'
57 (short 's'
42 <> long "server"
58 <> long "server"
59+ <> help
60+ "A path to the file containing the specification that will be \
43− <> help "The specification that will be used for the server of the API.")
61+ \used for the server of the API. Can be either a YAML or JSON file.")
44 <*> (flag'
62 <*> (flag'
45 Nothing
63 Nothing
46 (long "silent"
64 (long "silent"
47 <> help "Silence all output.")
65 <> help "Silence all output.")
48 <|> flag'
66 <|> flag'
49 (Just OnlyErrors)
67 (Just OnlyErrors)
50− (long "only-errors"
68+ (long "only-breaking"
51− <> help "Only report incompatibility errors in the output.")
69+ <> help "Only report breaking changes in the output.")
52 <|> flag'
70 <|> flag'
53 (Just All)
71 (Just All)
54 (long "all"
72 (long "all"
@@ -59,9 +77,12 @@ optionsParser =
59 <*> ((FileMode
77 <*> ((FileMode
60 <$> strOption
78 <$> strOption
61 (short 'o' <> long "output"
79 (short 'o' <> long "output"
62− <> help
80+ <> helpDoc
81+ (Just $
63− "The file path where the output should be writtrn. \
82+ par "The file path where the output should be written. If the option is omitted the result will be written to stdout."
64− \Leave blank to output result to stdout."))
83+ <$$> hardline <> par "The file extension is used to determine the type of the output file."
84+ <$$> hardline <> par "Supports many formats such as markdown, html, rtf, doc, txt, rst, and many more."
85+ <$$> hardline <> par "Leave out the extension to produce a self-contained HTML report with styling.")))
65 <|> pure StdoutMode)
86 <|> pure StdoutMode)
66 <*> (flag'
87 <*> (flag'
67 FoldingBlockquotesTreeStyle
88 FoldingBlockquotesTreeStyle
@@ -79,3 +100,6 @@ optionsParser =
79 "The report tree is structured using \
100 "The report tree is structured using \
80 \increasing levels of headers.")
101 \increasing levels of headers.")
81 <|> pure HeadersTreeStyle)
102 <|> pure HeadersTreeStyle)
103+
104+par :: String -> Doc
105+par = foldr1 (</>) . fmap string . words