mirror of
https://github.com/ilyakooo0/compaREST.git
synced 2024-09-11 06:25:40 +03:00
Better CLI docs (#106)
This commit is contained in:
GitHub
parent
dcd32cbdd9
commit
a501f6ed41
62
README.md
62
README.md
@ -6,3 +6,65 @@
|
||||
[](LICENSE)
|
||||
|
||||
Compatibility checker for OpenAPI
|
||||
|
||||
|
||||
```
|
||||
Usage: openapi-diff (-c|--client ARG) (-s|--server ARG)
|
||||
[--silent | --only-breaking | --all] [-o|--output ARG]
|
||||
[--folding-block-quotes-style | --header-style]
|
||||
A tool to check compatibility between two OpenApi specifications.
|
||||
|
||||
Usage examples
|
||||
|
||||
Compare files old.yaml with new.yaml and output the resulting report to
|
||||
stdout:
|
||||
|
||||
openapi-diff -c old.yaml -s new.yaml
|
||||
|
||||
Only output breaking changes and write a styled HTML report to file
|
||||
report.html:
|
||||
|
||||
openapi-diff -c old.yaml -s new.yaml --only-breaking -o report
|
||||
|
||||
Don't output anything, only fail if there are breaking changes:
|
||||
|
||||
openapi-diff -c old.json -s new.json --silent
|
||||
|
||||
Write full report suitable for embedding into a GitHub comment to
|
||||
report.html:
|
||||
|
||||
openapi-diff -c old.json -s new.json --folding-block-quotes-style -o report.html
|
||||
|
||||
Available options:
|
||||
-h,--help Show this help text
|
||||
-c,--client ARG A path to the file containing the specification that
|
||||
will be used for the client of the API. Can be either
|
||||
a YAML or JSON file.
|
||||
-s,--server ARG A path to the file containing the specification that
|
||||
will be used for the server of the API. Can be either
|
||||
a YAML or JSON file.
|
||||
--silent Silence all output.
|
||||
--only-breaking Only report breaking changes in the output.
|
||||
--all Report both incompatible and compatible changes.
|
||||
Compatible changes will not trigger a failure exit
|
||||
code.
|
||||
-o,--output ARG The file path where the output should be written. If
|
||||
the option is omitted the result will be written to
|
||||
stdout.
|
||||
|
||||
The file extension is used to determine the type of
|
||||
the output file.
|
||||
|
||||
Supports many formats such as markdown, html, rtf,
|
||||
doc, txt, rst, and many more.
|
||||
|
||||
Leave out the extension to produce a self-contained
|
||||
HTML report with styling.
|
||||
--folding-block-quotes-style
|
||||
The report tree is structured using summary/detail
|
||||
HTML elements and indented using block quotes. This
|
||||
style renders well on GitHub.Intended for HTML output
|
||||
format. Markdown has rendering bugs on GitHub.
|
||||
--header-style The report tree is structured using increasing levels
|
||||
of headers.
|
||||
```
|
||||
|
||||
@ -9,6 +9,7 @@ where
|
||||
import GHC.Generics (Generic)
|
||||
import OpenAPI.Checker.Report
|
||||
import Options.Applicative
|
||||
import Options.Applicative.Help hiding (fullDesc)
|
||||
|
||||
data Options = Options
|
||||
{ clientFile :: FilePath
|
||||
@ -28,7 +29,20 @@ optionsParserInfo =
|
||||
(helper <*> optionsParser)
|
||||
(fullDesc
|
||||
<> header "openapi-diff"
|
||||
<> progDesc "A tool to check compatibility between two OpenApi specifications.")
|
||||
<> progDescDoc
|
||||
(Just $
|
||||
par "A tool to check compatibility between two OpenApi specifications."
|
||||
<$$> hardline <> par "Usage examples" <> hardline
|
||||
<$$> indent
|
||||
4
|
||||
(par "Compare files old.yaml with new.yaml and output the resulting report to stdout:"
|
||||
<$$> hardline <> indent 4 "openapi-diff -c old.yaml -s new.yaml"
|
||||
<$$> hardline <> par "Only output breaking changes and write a styled HTML report to file report.html:"
|
||||
<$$> hardline <> indent 4 "openapi-diff -c old.yaml -s new.yaml --only-breaking -o report"
|
||||
<$$> hardline <> par "Don't output anything, only fail if there are breaking changes:"
|
||||
<$$> hardline <> indent 4 "openapi-diff -c old.json -s new.json --silent"
|
||||
<$$> hardline <> par "Write full report suitable for embedding into a GitHub comment to report.html:"
|
||||
<$$> hardline <> indent 4 "openapi-diff -c old.json -s new.json --folding-block-quotes-style -o report.html")))
|
||||
|
||||
optionsParser :: Parser Options
|
||||
optionsParser =
|
||||
@ -36,19 +50,23 @@ optionsParser =
|
||||
<$> strOption
|
||||
(short 'c'
|
||||
<> long "client"
|
||||
<> help "The specification that will be used for the client of the API.")
|
||||
<> help
|
||||
"A path to the file containing the specification that will be \
|
||||
\used for the client of the API. Can be either a YAML or JSON file.")
|
||||
<*> strOption
|
||||
(short 's'
|
||||
<> long "server"
|
||||
<> help "The specification that will be used for the server of the API.")
|
||||
<> help
|
||||
"A path to the file containing the specification that will be \
|
||||
\used for the server of the API. Can be either a YAML or JSON file.")
|
||||
<*> (flag'
|
||||
Nothing
|
||||
(long "silent"
|
||||
<> help "Silence all output.")
|
||||
<|> flag'
|
||||
(Just OnlyErrors)
|
||||
(long "only-errors"
|
||||
<> help "Only report incompatibility errors in the output.")
|
||||
(long "only-breaking"
|
||||
<> help "Only report breaking changes in the output.")
|
||||
<|> flag'
|
||||
(Just All)
|
||||
(long "all"
|
||||
@ -59,9 +77,12 @@ optionsParser =
|
||||
<*> ((FileMode
|
||||
<$> strOption
|
||||
(short 'o' <> long "output"
|
||||
<> help
|
||||
"The file path where the output should be writtrn. \
|
||||
\Leave blank to output result to stdout."))
|
||||
<> helpDoc
|
||||
(Just $
|
||||
par "The file path where the output should be written. If the option is omitted the result will be written to stdout."
|
||||
<$$> hardline <> par "The file extension is used to determine the type of the output file."
|
||||
<$$> hardline <> par "Supports many formats such as markdown, html, rtf, doc, txt, rst, and many more."
|
||||
<$$> hardline <> par "Leave out the extension to produce a self-contained HTML report with styling.")))
|
||||
<|> pure StdoutMode)
|
||||
<*> (flag'
|
||||
FoldingBlockquotesTreeStyle
|
||||
@ -79,3 +100,6 @@ optionsParser =
|
||||
"The report tree is structured using \
|
||||
\increasing levels of headers.")
|
||||
<|> pure HeadersTreeStyle)
|
||||
|
||||
par :: String -> Doc
|
||||
par = foldr1 (</>) . fmap string . words
|
||||
|
||||
Loading…
Reference in New Issue
Block a user