git.iko.soy/typeable/compaREST
on master help sign in
Better CLI docs (#106)
commita501f6ed419a2a84640d29922a973709476952e0 authoriko <ilyakooo0@gmail.com> dateThu 22 Jul 2021, 19:07 (5 years ago) parentdcd32cb
2 files changed+94−8
compare with master
unifiedsplit
README.md+62 app/OpenAPI/Checker/Options.hs+32−8
README.md+62
@@ -6,3 +6,65 @@
66[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
77
88Compatibility 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
99import GHC.Generics (Generic)
1010import OpenAPI.Checker.Report
1111import Options.Applicative
12+import Options.Applicative.Help hiding (fullDesc)
1213
1314data Options = Options
1415 { clientFile :: FilePath
@@ -28,7 +29,20 @@ optionsParserInfo =
2829 (helper <*> optionsParser)
2930 (fullDesc
3031 <> header "openapi-diff"
31− <> progDesc "A tool to check compatibility between two OpenApi specifications.")
32+ <> progDescDoc
33+ (Just $
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")))
3246
3347optionsParser :: Parser Options
3448optionsParser =
@@ -36,19 +50,23 @@ optionsParser =
3650 <$> strOption
3751 (short 'c'
3852 <> long "client"
39− <> help "The specification that will be used for the client of the API.")
53+ <> help
54+ "A path to the file containing the specification that will be \
55+ \used for the client of the API. Can be either a YAML or JSON file.")
4056 <*> strOption
4157 (short 's'
4258 <> long "server"
43− <> help "The specification that will be used for the server of the API.")
59+ <> help
60+ "A path to the file containing the specification that will be \
61+ \used for the server of the API. Can be either a YAML or JSON file.")
4462 <*> (flag'
4563 Nothing
4664 (long "silent"
4765 <> help "Silence all output.")
4866 <|> flag'
4967 (Just OnlyErrors)
50− (long "only-errors"
51− <> help "Only report incompatibility errors in the output.")
68+ (long "only-breaking"
69+ <> help "Only report breaking changes in the output.")
5270 <|> flag'
5371 (Just All)
5472 (long "all"
@@ -59,9 +77,12 @@ optionsParser =
5977 <*> ((FileMode
6078 <$> strOption
6179 (short 'o' <> long "output"
62− <> help
63− "The file path where the output should be writtrn. \
64− \Leave blank to output result to stdout."))
80+ <> helpDoc
81+ (Just $
82+ par "The file path where the output should be written. If the option is omitted the result will be written 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.")))
6586 <|> pure StdoutMode)
6687 <*> (flag'
6788 FoldingBlockquotesTreeStyle
@@ -79,3 +100,6 @@ optionsParser =
79100 "The report tree is structured using \
80101 \increasing levels of headers.")
81102 <|> pure HeadersTreeStyle)
103+
104+par :: String -> Doc
105+par = foldr1 (</>) . fmap string . words