3120 lines
155 KiB
HTML
3120 lines
155 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="Asciidoctor 1.5.5">
|
||
<meta name="author" content="Robert Winkler">
|
||
<title>Swagger2Markup Documentation</title>
|
||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
|
||
<style>
|
||
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
|
||
/* Remove comment around @import statement below when using as a custom stylesheet */
|
||
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
|
||
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
|
||
audio,canvas,video{display:inline-block}
|
||
audio:not([controls]){display:none;height:0}
|
||
[hidden],template{display:none}
|
||
script{display:none!important}
|
||
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
|
||
a{background:transparent}
|
||
a:focus{outline:thin dotted}
|
||
a:active,a:hover{outline:0}
|
||
h1{font-size:2em;margin:.67em 0}
|
||
abbr[title]{border-bottom:1px dotted}
|
||
b,strong{font-weight:bold}
|
||
dfn{font-style:italic}
|
||
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
|
||
mark{background:#ff0;color:#000}
|
||
code,kbd,pre,samp{font-family:monospace;font-size:1em}
|
||
pre{white-space:pre-wrap}
|
||
q{quotes:"\201C" "\201D" "\2018" "\2019"}
|
||
small{font-size:80%}
|
||
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
|
||
sup{top:-.5em}
|
||
sub{bottom:-.25em}
|
||
img{border:0}
|
||
svg:not(:root){overflow:hidden}
|
||
figure{margin:0}
|
||
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
|
||
legend{border:0;padding:0}
|
||
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
|
||
button,input{line-height:normal}
|
||
button,select{text-transform:none}
|
||
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
|
||
button[disabled],html input[disabled]{cursor:default}
|
||
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
|
||
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
|
||
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
|
||
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
|
||
textarea{overflow:auto;vertical-align:top}
|
||
table{border-collapse:collapse;border-spacing:0}
|
||
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
|
||
html,body{font-size:100%}
|
||
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
|
||
a:hover{cursor:pointer}
|
||
img,object,embed{max-width:100%;height:auto}
|
||
object,embed{height:100%}
|
||
img{-ms-interpolation-mode:bicubic}
|
||
.left{float:left!important}
|
||
.right{float:right!important}
|
||
.text-left{text-align:left!important}
|
||
.text-right{text-align:right!important}
|
||
.text-center{text-align:center!important}
|
||
.text-justify{text-align:justify!important}
|
||
.hide{display:none}
|
||
img,object,svg{display:inline-block;vertical-align:middle}
|
||
textarea{height:auto;min-height:50px}
|
||
select{width:100%}
|
||
.center{margin-left:auto;margin-right:auto}
|
||
.spread{width:100%}
|
||
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
|
||
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
|
||
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
|
||
a{color:#2156a5;text-decoration:underline;line-height:inherit}
|
||
a:hover,a:focus{color:#1d4b8f}
|
||
a img{border:none}
|
||
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
|
||
p aside{font-size:.875em;line-height:1.35;font-style:italic}
|
||
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
|
||
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
|
||
h1{font-size:2.125em}
|
||
h2{font-size:1.6875em}
|
||
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
|
||
h4,h5{font-size:1.125em}
|
||
h6{font-size:1em}
|
||
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
|
||
em,i{font-style:italic;line-height:inherit}
|
||
strong,b{font-weight:bold;line-height:inherit}
|
||
small{font-size:60%;line-height:inherit}
|
||
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
|
||
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
|
||
ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em}
|
||
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
|
||
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
|
||
ul.square{list-style-type:square}
|
||
ul.circle{list-style-type:circle}
|
||
ul.disc{list-style-type:disc}
|
||
ul.no-bullet{list-style:none}
|
||
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
|
||
dl dt{margin-bottom:.3125em;font-weight:bold}
|
||
dl dd{margin-bottom:1.25em}
|
||
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
|
||
abbr{text-transform:none}
|
||
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
|
||
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
|
||
blockquote cite:before{content:"\2014 \0020"}
|
||
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
|
||
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
|
||
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
|
||
h1{font-size:2.75em}
|
||
h2{font-size:2.3125em}
|
||
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
|
||
h4{font-size:1.4375em}}
|
||
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
|
||
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
|
||
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
|
||
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
|
||
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
|
||
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
|
||
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
|
||
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
|
||
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
|
||
.clearfix:after,.float-group:after{clear:both}
|
||
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
|
||
*:not(pre)>code.nobreak{word-wrap:normal}
|
||
*:not(pre)>code.nowrap{white-space:nowrap}
|
||
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
|
||
em em{font-style:normal}
|
||
strong strong{font-weight:400}
|
||
.keyseq{color:rgba(51,51,51,.8)}
|
||
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
|
||
.keyseq kbd:first-child{margin-left:0}
|
||
.keyseq kbd:last-child{margin-right:0}
|
||
.menuseq,.menu{color:rgba(0,0,0,.8)}
|
||
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
|
||
b.button:before{content:"[";padding:0 3px 0 2px}
|
||
b.button:after{content:"]";padding:0 2px 0 3px}
|
||
p a>code:hover{color:rgba(0,0,0,.9)}
|
||
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
|
||
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
|
||
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
|
||
#content{margin-top:1.25em}
|
||
#content:before{content:none}
|
||
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
|
||
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
|
||
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
|
||
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
|
||
#header .details span:first-child{margin-left:-.125em}
|
||
#header .details span.email a{color:rgba(0,0,0,.85)}
|
||
#header .details br{display:none}
|
||
#header .details br+span:before{content:"\00a0\2013\00a0"}
|
||
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
|
||
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
|
||
#header #revnumber{text-transform:capitalize}
|
||
#header #revnumber:after{content:"\00a0"}
|
||
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
|
||
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
|
||
#toc>ul{margin-left:.125em}
|
||
#toc ul.sectlevel0>li>a{font-style:italic}
|
||
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
|
||
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
|
||
#toc li{line-height:1.3334;margin-top:.3334em}
|
||
#toc a{text-decoration:none}
|
||
#toc a:active{text-decoration:underline}
|
||
#toctitle{color:#7a2518;font-size:1.2em}
|
||
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
|
||
body.toc2{padding-left:15em;padding-right:0}
|
||
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
|
||
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
|
||
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
|
||
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
|
||
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
|
||
body.toc2.toc-right{padding-left:0;padding-right:15em}
|
||
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}
|
||
@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
|
||
#toc.toc2{width:20em}
|
||
#toc.toc2 #toctitle{font-size:1.375em}
|
||
#toc.toc2>ul{font-size:.95em}
|
||
#toc.toc2 ul ul{padding-left:1.25em}
|
||
body.toc2.toc-right{padding-left:0;padding-right:20em}}
|
||
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
|
||
#content #toc>:first-child{margin-top:0}
|
||
#content #toc>:last-child{margin-bottom:0}
|
||
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
|
||
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
|
||
.sect1{padding-bottom:.625em}
|
||
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}
|
||
.sect1+.sect1{border-top:1px solid #efefed}
|
||
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
|
||
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
|
||
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
|
||
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
|
||
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
|
||
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
|
||
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
|
||
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
|
||
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
|
||
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
|
||
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
|
||
.admonitionblock>table td.icon{text-align:center;width:80px}
|
||
.admonitionblock>table td.icon img{max-width:none}
|
||
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
|
||
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
|
||
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
|
||
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
|
||
.exampleblock>.content>:first-child{margin-top:0}
|
||
.exampleblock>.content>:last-child{margin-bottom:0}
|
||
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
|
||
.sidebarblock>:first-child{margin-top:0}
|
||
.sidebarblock>:last-child{margin-bottom:0}
|
||
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
|
||
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
|
||
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
|
||
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
|
||
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
|
||
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
|
||
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
|
||
@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
|
||
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
|
||
.listingblock pre.highlightjs{padding:0}
|
||
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
|
||
.listingblock pre.prettyprint{border-width:0}
|
||
.listingblock>.content{position:relative}
|
||
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
|
||
.listingblock:hover code[data-lang]:before{display:block}
|
||
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
|
||
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
|
||
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
|
||
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
|
||
table.pyhltable td.code{padding-left:.75em;padding-right:0}
|
||
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
|
||
pre.pygments .lineno{display:inline-block;margin-right:.25em}
|
||
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
|
||
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
|
||
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
|
||
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
|
||
.quoteblock blockquote{margin:0;padding:0;border:0}
|
||
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
|
||
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
|
||
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
|
||
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
|
||
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
|
||
.quoteblock .quoteblock blockquote:before{display:none}
|
||
.verseblock{margin:0 1em 1.25em 1em}
|
||
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
|
||
.verseblock pre strong{font-weight:400}
|
||
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
|
||
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
|
||
.quoteblock .attribution br,.verseblock .attribution br{display:none}
|
||
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
|
||
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
|
||
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
|
||
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
|
||
table.tableblock{max-width:100%;border-collapse:separate}
|
||
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
|
||
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
|
||
table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0}
|
||
table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0}
|
||
table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0}
|
||
table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0}
|
||
table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0}
|
||
table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0}
|
||
table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0}
|
||
table.frame-all{border-width:1px}
|
||
table.frame-sides{border-width:0 1px}
|
||
table.frame-topbot{border-width:1px 0}
|
||
th.halign-left,td.halign-left{text-align:left}
|
||
th.halign-right,td.halign-right{text-align:right}
|
||
th.halign-center,td.halign-center{text-align:center}
|
||
th.valign-top,td.valign-top{vertical-align:top}
|
||
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
|
||
th.valign-middle,td.valign-middle{vertical-align:middle}
|
||
table thead th,table tfoot th{font-weight:bold}
|
||
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
|
||
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
|
||
p.tableblock>code:only-child{background:none;padding:0}
|
||
p.tableblock{font-size:1em}
|
||
td>div.verse{white-space:pre}
|
||
ol{margin-left:1.75em}
|
||
ul li ol{margin-left:1.5em}
|
||
dl dd{margin-left:1.125em}
|
||
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
|
||
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
|
||
ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none}
|
||
ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em}
|
||
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em}
|
||
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px}
|
||
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
|
||
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
|
||
ul.inline>li>*{display:block}
|
||
.unstyled dl dt{font-weight:400;font-style:normal}
|
||
ol.arabic{list-style-type:decimal}
|
||
ol.decimal{list-style-type:decimal-leading-zero}
|
||
ol.loweralpha{list-style-type:lower-alpha}
|
||
ol.upperalpha{list-style-type:upper-alpha}
|
||
ol.lowerroman{list-style-type:lower-roman}
|
||
ol.upperroman{list-style-type:upper-roman}
|
||
ol.lowergreek{list-style-type:lower-greek}
|
||
.hdlist>table,.colist>table{border:0;background:none}
|
||
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
|
||
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
|
||
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
|
||
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
|
||
.colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}
|
||
.colist>table tr>td:last-of-type{padding:.25em 0}
|
||
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
|
||
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
|
||
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
|
||
.imageblock>.title{margin-bottom:0}
|
||
.imageblock.thumb,.imageblock.th{border-width:6px}
|
||
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
|
||
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
|
||
.image.left{margin-right:.625em}
|
||
.image.right{margin-left:.625em}
|
||
a.image{text-decoration:none;display:inline-block}
|
||
a.image object{pointer-events:none}
|
||
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
|
||
sup.footnote a,sup.footnoteref a{text-decoration:none}
|
||
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
|
||
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
|
||
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
|
||
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;text-indent:-1.05em;margin-bottom:.2em}
|
||
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
|
||
#footnotes .footnote:last-of-type{margin-bottom:0}
|
||
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
|
||
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
|
||
.gist .file-data>table td.line-data{width:99%}
|
||
div.unbreakable{page-break-inside:avoid}
|
||
.big{font-size:larger}
|
||
.small{font-size:smaller}
|
||
.underline{text-decoration:underline}
|
||
.overline{text-decoration:overline}
|
||
.line-through{text-decoration:line-through}
|
||
.aqua{color:#00bfbf}
|
||
.aqua-background{background-color:#00fafa}
|
||
.black{color:#000}
|
||
.black-background{background-color:#000}
|
||
.blue{color:#0000bf}
|
||
.blue-background{background-color:#0000fa}
|
||
.fuchsia{color:#bf00bf}
|
||
.fuchsia-background{background-color:#fa00fa}
|
||
.gray{color:#606060}
|
||
.gray-background{background-color:#7d7d7d}
|
||
.green{color:#006000}
|
||
.green-background{background-color:#007d00}
|
||
.lime{color:#00bf00}
|
||
.lime-background{background-color:#00fa00}
|
||
.maroon{color:#600000}
|
||
.maroon-background{background-color:#7d0000}
|
||
.navy{color:#000060}
|
||
.navy-background{background-color:#00007d}
|
||
.olive{color:#606000}
|
||
.olive-background{background-color:#7d7d00}
|
||
.purple{color:#600060}
|
||
.purple-background{background-color:#7d007d}
|
||
.red{color:#bf0000}
|
||
.red-background{background-color:#fa0000}
|
||
.silver{color:#909090}
|
||
.silver-background{background-color:#bcbcbc}
|
||
.teal{color:#006060}
|
||
.teal-background{background-color:#007d7d}
|
||
.white{color:#bfbfbf}
|
||
.white-background{background-color:#fafafa}
|
||
.yellow{color:#bfbf00}
|
||
.yellow-background{background-color:#fafa00}
|
||
span.icon>.fa{cursor:default}
|
||
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
|
||
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
|
||
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
|
||
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
|
||
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
|
||
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
|
||
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
|
||
.conum[data-value] *{color:#fff!important}
|
||
.conum[data-value]+b{display:none}
|
||
.conum[data-value]:after{content:attr(data-value)}
|
||
pre .conum[data-value]{position:relative;top:-.125em}
|
||
b.conum *{color:inherit!important}
|
||
.conum:not([data-value]):empty{display:none}
|
||
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
|
||
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
|
||
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
|
||
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
|
||
p{margin-bottom:1.25rem}
|
||
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
|
||
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
|
||
.print-only{display:none!important}
|
||
@media print{@page{margin:1.25cm .75cm}
|
||
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
|
||
a{color:inherit!important;text-decoration:underline!important}
|
||
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
|
||
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
|
||
abbr[title]:after{content:" (" attr(title) ")"}
|
||
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
|
||
thead{display:table-header-group}
|
||
svg{max-width:100%}
|
||
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
|
||
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
|
||
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
|
||
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
|
||
.sect1{padding-bottom:0!important}
|
||
.sect1+.sect1{border:0!important}
|
||
#header>h1:first-child{margin-top:1.25rem}
|
||
body.book #header{text-align:center}
|
||
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
|
||
body.book #header .details{border:0!important;display:block;padding:0!important}
|
||
body.book #header .details span:first-child{margin-left:0!important}
|
||
body.book #header .details br{display:block}
|
||
body.book #header .details br+span:before{content:none!important}
|
||
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
|
||
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
|
||
.listingblock code[data-lang]:before{display:block}
|
||
#footer{background:none!important;padding:0 .9375em}
|
||
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
|
||
.hide-on-print{display:none!important}
|
||
.print-only{display:block!important}
|
||
.hide-for-print{display:none!important}
|
||
.show-for-print{display:inherit!important}}
|
||
</style>
|
||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
|
||
<style>
|
||
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
|
||
/*pre.CodeRay {background-color:#f7f7f8;}*/
|
||
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
|
||
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
|
||
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
|
||
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
|
||
table.CodeRay td{vertical-align: top;line-height:1.45}
|
||
table.CodeRay td.line-numbers{text-align:right}
|
||
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
|
||
table.CodeRay td.code{padding:0 0 0 .5em}
|
||
table.CodeRay td.code>pre{padding:0}
|
||
.CodeRay .debug{color:#fff !important;background:#000080 !important}
|
||
.CodeRay .annotation{color:#007}
|
||
.CodeRay .attribute-name{color:#000080}
|
||
.CodeRay .attribute-value{color:#700}
|
||
.CodeRay .binary{color:#509}
|
||
.CodeRay .comment{color:#998;font-style:italic}
|
||
.CodeRay .char{color:#04d}
|
||
.CodeRay .char .content{color:#04d}
|
||
.CodeRay .char .delimiter{color:#039}
|
||
.CodeRay .class{color:#458;font-weight:bold}
|
||
.CodeRay .complex{color:#a08}
|
||
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
|
||
.CodeRay .color{color:#099}
|
||
.CodeRay .class-variable{color:#369}
|
||
.CodeRay .decorator{color:#b0b}
|
||
.CodeRay .definition{color:#099}
|
||
.CodeRay .delimiter{color:#000}
|
||
.CodeRay .doc{color:#970}
|
||
.CodeRay .doctype{color:#34b}
|
||
.CodeRay .doc-string{color:#d42}
|
||
.CodeRay .escape{color:#666}
|
||
.CodeRay .entity{color:#800}
|
||
.CodeRay .error{color:#808}
|
||
.CodeRay .exception{color:inherit}
|
||
.CodeRay .filename{color:#099}
|
||
.CodeRay .function{color:#900;font-weight:bold}
|
||
.CodeRay .global-variable{color:#008080}
|
||
.CodeRay .hex{color:#058}
|
||
.CodeRay .integer,.CodeRay .float{color:#099}
|
||
.CodeRay .include{color:#555}
|
||
.CodeRay .inline{color:#000}
|
||
.CodeRay .inline .inline{background:#ccc}
|
||
.CodeRay .inline .inline .inline{background:#bbb}
|
||
.CodeRay .inline .inline-delimiter{color:#d14}
|
||
.CodeRay .inline-delimiter{color:#d14}
|
||
.CodeRay .important{color:#555;font-weight:bold}
|
||
.CodeRay .interpreted{color:#b2b}
|
||
.CodeRay .instance-variable{color:#008080}
|
||
.CodeRay .label{color:#970}
|
||
.CodeRay .local-variable{color:#963}
|
||
.CodeRay .octal{color:#40e}
|
||
.CodeRay .predefined{color:#369}
|
||
.CodeRay .preprocessor{color:#579}
|
||
.CodeRay .pseudo-class{color:#555}
|
||
.CodeRay .directive{font-weight:bold}
|
||
.CodeRay .type{font-weight:bold}
|
||
.CodeRay .predefined-type{color:inherit}
|
||
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
|
||
.CodeRay .key{color:#808}
|
||
.CodeRay .key .delimiter{color:#606}
|
||
.CodeRay .key .char{color:#80f}
|
||
.CodeRay .value{color:#088}
|
||
.CodeRay .regexp .delimiter{color:#808}
|
||
.CodeRay .regexp .content{color:#808}
|
||
.CodeRay .regexp .modifier{color:#808}
|
||
.CodeRay .regexp .char{color:#d14}
|
||
.CodeRay .regexp .function{color:#404;font-weight:bold}
|
||
.CodeRay .string{color:#d20}
|
||
.CodeRay .string .string .string{background:#ffd0d0}
|
||
.CodeRay .string .content{color:#d14}
|
||
.CodeRay .string .char{color:#d14}
|
||
.CodeRay .string .delimiter{color:#d14}
|
||
.CodeRay .shell{color:#d14}
|
||
.CodeRay .shell .delimiter{color:#d14}
|
||
.CodeRay .symbol{color:#990073}
|
||
.CodeRay .symbol .content{color:#a60}
|
||
.CodeRay .symbol .delimiter{color:#630}
|
||
.CodeRay .tag{color:#008080}
|
||
.CodeRay .tag-special{color:#d70}
|
||
.CodeRay .variable{color:#036}
|
||
.CodeRay .insert{background:#afa}
|
||
.CodeRay .delete{background:#faa}
|
||
.CodeRay .change{color:#aaf;background:#007}
|
||
.CodeRay .head{color:#f8f;background:#505}
|
||
.CodeRay .insert .insert{color:#080}
|
||
.CodeRay .delete .delete{color:#800}
|
||
.CodeRay .change .change{color:#66f}
|
||
.CodeRay .head .head{color:#f4f}
|
||
</style>
|
||
</head>
|
||
<body class="book toc2 toc-left">
|
||
<div id="header">
|
||
<h1>Swagger2Markup Documentation</h1>
|
||
<div class="details">
|
||
<span id="author" class="author">Robert Winkler</span><br>
|
||
<span id="revnumber">version 1.3.1,</span>
|
||
<span id="revdate">2017-10-09</span>
|
||
</div>
|
||
<div id="toc" class="toc2">
|
||
<div id="toctitle">Table of Contents</div>
|
||
<ul class="sectlevel1">
|
||
<li><a href="#_introduction">1. Introduction</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_asciidoc">1.1. AsciiDoc</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_getting_started">2. Getting started</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_gradle">2.1. Gradle</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_release">2.1.1. Release</a></li>
|
||
<li><a href="#_snapshot">2.1.2. Snapshot</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_maven">2.2. Maven</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_release_2">2.2.1. Release</a></li>
|
||
<li><a href="#_snapshot_2">2.2.2. Snapshot</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_swagger2markup_api">3. Swagger2Markup API</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_usage_guide">3.1. Usage guide</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_conversion_of_a_local_swagger_file">3.1.1. Conversion of a local Swagger file</a></li>
|
||
<li><a href="#_conversion_of_a_remote_swagger_file">3.1.2. Conversion of a remote Swagger file</a></li>
|
||
<li><a href="#_conversion_into_a_file">3.1.3. Conversion into a file</a></li>
|
||
<li><a href="#_conversion_to_a_string">3.1.4. Conversion to a String</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_configuration">3.2. Configuration</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_configuration_using_the_builder">3.2.1. Configuration using the Builder</a></li>
|
||
<li><a href="#_configuration_from_a_properties_file">3.2.2. Configuration from a Properties file</a></li>
|
||
<li><a href="#_configuration_from_a_map">3.2.3. Configuration from a Map</a></li>
|
||
<li><a href="#_configuration_from_a_apache_commons_configuration">3.2.4. Configuration from a Apache Commons Configuration</a></li>
|
||
<li><a href="#_swagger2markup_properties">3.2.5. Swagger2Markup properties</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_logging">3.3. Logging</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_advanced_usage">4. Advanced usage</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#swagger_operationId">4.1. Swagger operationId</a></li>
|
||
<li><a href="#_swagger_schema_title">4.2. Swagger schema title</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_extension_spi">5. Extension SPI</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_creation_of_an_extension">5.1. Creation of an extension</a></li>
|
||
<li><a href="#_registration_of_an_extension">5.2. Registration of an extension</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_automatic_registration">5.2.1. Automatic registration</a></li>
|
||
<li><a href="#_manual_registration">5.2.2. Manual registration</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_extensions_points">5.3. Extensions points</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_overviewdocumentextension">5.3.1. OverviewDocumentExtension</a></li>
|
||
<li><a href="#_pathsdocumentextension">5.3.2. PathsDocumentExtension</a></li>
|
||
<li><a href="#_securitydocumentextension">5.3.3. SecurityDocumentExtension</a></li>
|
||
<li><a href="#_definitionsdocumentextension">5.3.4. DefinitionsDocumentExtension</a></li>
|
||
<li><a href="#_swaggermodelextension">5.3.5. SwaggerModelExtension</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#extension_commons_content_markup">5.4. Content markup language</a></li>
|
||
<li><a href="#_provided_extensions">5.5. Provided Extensions</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#extension_import_files">5.5.1. Dynamic file import extension</a></li>
|
||
<li><a href="#extension_spring_restdocs">5.5.2. Spring RestDocs extension</a></li>
|
||
<li><a href="#extension_import_schemas">5.5.3. Schema file import extension</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_gradle_plugin">6. Gradle Plugin</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_usage_guide_5">6.1. Usage guide</a></li>
|
||
<li><a href="#_configuration_3">6.2. Configuration</a></li>
|
||
<li><a href="#_example">6.3. Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_maven_plugin">7. Maven Plugin</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_usage_guide_6">7.1. Usage guide</a></li>
|
||
<li><a href="#_configuration_4">7.2. Configuration</a></li>
|
||
<li><a href="#_example_2">7.3. Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_command_line_interface">8. Command Line Interface</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_usage_guide_7">8.1. Usage guide</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_show_help">8.1.1. Show help</a></li>
|
||
<li><a href="#_conversion_into_a_folder">8.1.2. Conversion into a folder</a></li>
|
||
<li><a href="#_conversion_into_a_file_2">8.1.3. Conversion into a file</a></li>
|
||
<li><a href="#_conversion_of_a_remote_swagger_file_2">8.1.4. Conversion of a remote Swagger file</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_configuration_5">8.2. Configuration</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_docker_image">9. Docker image</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_usage_guide_8">9.1. Usage guide</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_spring_boot_and_springfox">10. Spring Boot and Springfox</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_demo">10.1. Demo</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_contributing">11. Contributing</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_questions">11.1. Questions</a></li>
|
||
<li><a href="#_bugs">11.2. Bugs</a></li>
|
||
<li><a href="#_enhancements">11.3. Enhancements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_license">12. License</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="content">
|
||
<div class="sect1">
|
||
<h2 id="_introduction"><a class="anchor" href="#_introduction"></a><a class="link" href="#_introduction">1. Introduction</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>The primary goal of this project is to <strong>simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation</strong> produced by <a href="https://github.com/swagger-api">Swagger</a>. The result is intended to be an <strong>up-to-date, easy-to-read, on- and offline user guide</strong>. The output of Swagger2Markup can be used as an alternative to <a href="https://github.com/swagger-api/swagger-ui">swagger-ui</a> and can be served as static content.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The Swagger Specification has been donated to to the <a href="https://openapis.org/">Open API Initiative (OAI)</a> and has been renamed to <a href="https://github.com/OAI/OpenAPI-Specification">OpenAPI Specification</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup converts a Swagger JSON or YAML specification into either <strong>AsciiDoc</strong>, <strong>GitHub Flavored Markdown</strong> or <strong>Atlassian Confluence Wiki</strong> documents which can be combined with hand-written Markup documentation. The Swagger source file can be located locally or remotely via HTTP. Internally Swagger2Markup uses the <em>official</em> <a href="https://github.com/swagger-api/swagger-parser">swagger-parser</a> and <a href="https://github.com/Swagger2Markup/markup-document-builder">markup-document-builder</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>You can use Swagger2Markup to convert your contract-first Swagger YAML file into Markup. As an alternative, you can choose the code-first approach and use Swagger2Markup together with <a href="https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X">Swagger JAX-RS</a>, <a href="https://github.com/springfox/springfox">Springfox</a> or <a href="https://github.com/spring-projects/spring-restdocs">spring-restdocs</a>. If you are are Gradle or Maven user, you can also use the <a href="https://github.com/Swagger2Markup/swagger2markup-gradle-plugin">Swagger2Markup Gradle Plugin</a> or <a href="https://github.com/redowl/swagger2markup-maven-plugin">Swagger2markup Maven Plugin</a>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The project requires at least JDK 8.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_asciidoc"><a class="anchor" href="#_asciidoc"></a><a class="link" href="#_asciidoc">1.1. AsciiDoc</a></h3>
|
||
<div class="paragraph">
|
||
<p><a href="http://asciidoctor.org/docs/asciidoc-writers-guide/">AsciiDoc</a> is preferable to Markdown as it has more features. AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to <strong>HTML</strong>, <strong>PDF</strong> and <strong>EPUB</strong>. AsciiDoc is much better suited for describing public APIs than <strong>JavaDoc</strong> or <strong>Annotations</strong>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>You can generate your HTML5, PDF and EPUB documentation via <a href="https://github.com/asciidoctor/asciidoctorj">asciidoctorj</a> or even better via the <a href="https://github.com/asciidoctor/asciidoctor-gradle-plugin">asciidoctor-gradle-plugin</a> or <a href="https://github.com/asciidoctor/asciidoctor-maven-plugin">asciidoctor-maven-plugin</a>.</p>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="images/Swagger2Markup.PNG" alt="Swagger2Markup">
|
||
</div>
|
||
<div class="title">Figure 1. HTML example using AsciiDoctor - path section</div>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="images/Swagger2Markup_definitions.PNG" alt="Swagger2Markup definitions">
|
||
</div>
|
||
<div class="title">Figure 2. HTML example using AsciiDoctor - definition section</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_getting_started"><a class="anchor" href="#_getting_started"></a><a class="link" href="#_getting_started">2. Getting started</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup is a standard .jar file. To start using it, you need to add the library to your project’s classpath. Swagger2Markup is published in JCenter and Maven Central. The artifacts can be viewed at the following locations:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Releases: <a href="https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup/" class="bare">https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup/</a></p>
|
||
</li>
|
||
<li>
|
||
<p>Snapshots: <a href="https://oss.jfrog.org/simple/oss-snapshot-local/io/github/swagger2markup/swagger2markup/" class="bare">https://oss.jfrog.org/simple/oss-snapshot-local/io/github/swagger2markup/swagger2markup/</a></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If you use Gradle or Maven, you can include Swagger2Markup as follows.</p>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
The <strong>groupId</strong> has been changed from <strong>io.github.robwin</strong> to <strong>io.github.swagger2markup</strong>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_gradle"><a class="anchor" href="#_gradle"></a><a class="link" href="#_gradle">2.1. Gradle</a></h3>
|
||
<div class="sect3">
|
||
<h4 id="_release"><a class="anchor" href="#_release"></a><a class="link" href="#_release">2.1.1. Release</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">repositories {
|
||
jCenter()
|
||
}
|
||
|
||
compile "io.github.swagger2markup:swagger2markup:1.3.1"</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_snapshot"><a class="anchor" href="#_snapshot"></a><a class="link" href="#_snapshot">2.1.2. Snapshot</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">repositories {
|
||
maven { url <span class="string"><span class="delimiter">'</span><span class="content">http://oss.jfrog.org/artifactory/oss-snapshot-local/</span><span class="delimiter">'</span></span> }
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_maven"><a class="anchor" href="#_maven"></a><a class="link" href="#_maven">2.2. Maven</a></h3>
|
||
<div class="sect3">
|
||
<h4 id="_release_2"><a class="anchor" href="#_release_2"></a><a class="link" href="#_release_2">2.2.1. Release</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><repositories></span>
|
||
<span class="tag"><repository></span>
|
||
<span class="tag"><snapshots></span>
|
||
<span class="tag"><enabled></span>false<span class="tag"></enabled></span>
|
||
<span class="tag"></snapshots></span>
|
||
<span class="tag"><id></span>jcenter-releases<span class="tag"></id></span>
|
||
<span class="tag"><name></span>jcenter<span class="tag"></name></span>
|
||
<span class="tag"><url></span>http://jcenter.bintray.com<span class="tag"></url></span>
|
||
<span class="tag"></repository></span>
|
||
<span class="tag"></repositories></span>
|
||
|
||
<span class="tag"><dependency></span>
|
||
<span class="tag"><groupId></span>io.github.swagger2markup<span class="tag"></groupId></span>
|
||
<span class="tag"><artifactId></span>swagger2markup<span class="tag"></artifactId></span>
|
||
<span class="tag"><version></span>1.3.1<span class="tag"></version></span>
|
||
<span class="tag"></dependency></span></code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_snapshot_2"><a class="anchor" href="#_snapshot_2"></a><a class="link" href="#_snapshot_2">2.2.2. Snapshot</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><repositories>
|
||
<repository>
|
||
<id>jcenter-snapshots</id>
|
||
<name>jcenter</name>
|
||
<url>http:<span class="comment">//oss.jfrog.org/artifactory/oss-snapshot-local/</url></span>
|
||
</repository>
|
||
</repositories></code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_swagger2markup_api"><a class="anchor" href="#_swagger2markup_api"></a><a class="link" href="#_swagger2markup_api">3. Swagger2Markup API</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="sect2">
|
||
<h3 id="_usage_guide"><a class="anchor" href="#_usage_guide"></a><a class="link" href="#_usage_guide">3.1. Usage guide</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup converts a Swagger JSON or YAML specification into either <strong>AsciiDoc</strong>, <strong>GitHub Flavored Markdown</strong> or <strong>Atlassian Confluence Wiki</strong> documents. By default the Swagger2Markup converts a Swagger specification into four AsciiDoc files: <em>overview.adoc</em>, <em>paths.adoc</em> , <em>security.adoc</em> and <em>definitions.adoc</em>. But you can also convert a Swagger specification into only one file or a String.</p>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_of_a_local_swagger_file"><a class="anchor" href="#_conversion_of_a_local_swagger_file"></a><a class="link" href="#_conversion_of_a_local_swagger_file">3.1.1. Conversion of a local Swagger file</a></h4>
|
||
<div class="paragraph">
|
||
<p>The entry point of the Swagger2Markup API is the <code>Swagger2MarkupConverter</code> class. This class provides static factory methods to create a <code>Swagger2MarkupConverter.Builder</code>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Path localSwaggerFile = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">/path/to/swagger.yaml</span><span class="delimiter">"</span></span>);
|
||
Path outputDirectory = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">build/asciidoc</span><span class="delimiter">"</span></span>);
|
||
|
||
Swagger2MarkupConverter.from(localSwaggerFile) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
.build() <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.toFolder(outputDirectory); <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConverter.Builder</code> by specifying the Path to the local file</p>
|
||
</li>
|
||
<li>
|
||
<p>Build an instance of the <code>Swagger2MarkupConverter</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Invoke <code>toFolder</code> by specifying the output directory</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_of_a_remote_swagger_file"><a class="anchor" href="#_conversion_of_a_remote_swagger_file"></a><a class="link" href="#_conversion_of_a_remote_swagger_file">3.1.2. Conversion of a remote Swagger file</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert a remote Swagger specification which must be accessible via HTTP.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">URL</span> remoteSwaggerFile = <span class="keyword">new</span> <span class="predefined-type">URL</span>(<span class="string"><span class="delimiter">"</span><span class="content">http://petstore.swagger.io/v2/swagger.json</span><span class="delimiter">"</span></span>);
|
||
Path outputDirectory = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">build/asciidoc</span><span class="delimiter">"</span></span>);
|
||
|
||
Swagger2MarkupConverter.from(remoteSwaggerFile) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
.build() <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.toFolder(outputDirectory); <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConverter.Builder</code> by specifying the URL to the remote file</p>
|
||
</li>
|
||
<li>
|
||
<p>Build an instance of the <code>Swagger2MarkupConverter</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Invoke <code>toFolder</code> by specifying the output directory</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_into_a_file"><a class="anchor" href="#_conversion_into_a_file"></a><a class="link" href="#_conversion_into_a_file">3.1.3. Conversion into a file</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert the Swagger specification into a file.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Path localSwaggerFile = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">/path/to/swagger.yaml</span><span class="delimiter">"</span></span>);
|
||
Path outputFile = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">build/swagger.adoc</span><span class="delimiter">"</span></span>);
|
||
|
||
Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.build()
|
||
.toFile(outputFile);</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_to_a_string"><a class="anchor" href="#_conversion_to_a_string"></a><a class="link" href="#_conversion_to_a_string">3.1.4. Conversion to a String</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert the Swagger specification to a String.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Path localSwaggerFile = Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">/path/to/swagger.yaml</span><span class="delimiter">"</span></span>);
|
||
|
||
<span class="predefined-type">String</span> documentation = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.build()
|
||
.toString();</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_configuration"><a class="anchor" href="#_configuration"></a><a class="link" href="#_configuration">3.2. Configuration</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides several options to configure the Swagger2MarkupConverter:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Using system properties</p>
|
||
</li>
|
||
<li>
|
||
<p>Using a fluent API</p>
|
||
</li>
|
||
<li>
|
||
<p>Using a properties file</p>
|
||
</li>
|
||
<li>
|
||
<p>Using a Java Map</p>
|
||
</li>
|
||
<li>
|
||
<p>Using Apache Commons Configuration</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_configuration_using_the_builder"><a class="anchor" href="#_configuration_using_the_builder"></a><a class="link" href="#_configuration_using_the_builder">3.2.1. Configuration using the Builder</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can configure the Swagger2MarkupConverter by using the <code>Swagger2MarkupConfigBuilder</code> to build a custom <code>Swagger2MarkupConfig</code>. The <code>Swagger2MarkupConfigBuilder</code> can be used to define Swagger2Markup properties with a fluent API.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Swagger2MarkupConfig config = <span class="keyword">new</span> Swagger2MarkupConfigBuilder() <i class="conum" data-value="1"></i><b>(1)</b>
|
||
.withMarkupLanguage(MarkupLanguage.MARKDOWN) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.withOutputLanguage(Language.DE) <i class="conum" data-value="3"></i><b>(3)</b>
|
||
.withPathsGroupedBy(GroupBy.TAGS) <i class="conum" data-value="4"></i><b>(4)</b>
|
||
.build(); <i class="conum" data-value="5"></i><b>(5)</b>
|
||
|
||
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.withConfig(config) <i class="conum" data-value="6"></i><b>(6)</b>
|
||
.build();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConfigBuilder</code> using the default constructor.</p>
|
||
</li>
|
||
<li>
|
||
<p>Configure the output <code>MarkupLanguage</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Configure the output <code>Language</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Configure additional Swagger2Markup properties</p>
|
||
</li>
|
||
<li>
|
||
<p>Build an instance of the <code>Swagger2MarkupConfig</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Use the custom Swagger2MarkupConfig</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>You can also create a <code>Swagger2MarkupConfig</code> from a Properties file, a <code>Map</code> or a Apache Commons Configuration.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_configuration_from_a_properties_file"><a class="anchor" href="#_configuration_from_a_properties_file"></a><a class="link" href="#_configuration_from_a_properties_file">3.2.2. Configuration from a Properties file</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Properties</span> properties = <span class="keyword">new</span> <span class="predefined-type">Properties</span>();
|
||
properties.load(DocumentationTest.class.getResourceAsStream(<span class="string"><span class="delimiter">"</span><span class="content">/config/config.properties</span><span class="delimiter">"</span></span>)); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
Swagger2MarkupConfig config = <span class="keyword">new</span> Swagger2MarkupConfigBuilder(properties) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.build();
|
||
|
||
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.withConfig(config)
|
||
.build();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Load a <code>Properties</code> file from the classpath or local filesystem.</p>
|
||
</li>
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConfigBuilder</code> using the proper constructor.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_configuration_from_a_map"><a class="anchor" href="#_configuration_from_a_map"></a><a class="link" href="#_configuration_from_a_map">3.2.3. Configuration from a Map</a></h4>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> configMap = <span class="keyword">new</span> <span class="predefined-type">HashMap</span><>(); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
configMap.put(Swagger2MarkupProperties.MARKUP_LANGUAGE, MarkupLanguage.MARKDOWN.toString());
|
||
configMap.put(Swagger2MarkupProperties.OUTPUT_LANGUAGE, Language.DE.toString());
|
||
configMap.put(Swagger2MarkupProperties.PATHS_GROUPED_BY, GroupBy.TAGS.toString());
|
||
|
||
Swagger2MarkupConfig config = <span class="keyword">new</span> Swagger2MarkupConfigBuilder(configMap) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.build();
|
||
|
||
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.withConfig(config)
|
||
.build();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create a <code>Map</code> and configure the <code>Swagger2MarkupProperties</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConfigBuilder</code> using the proper constructor.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_configuration_from_a_apache_commons_configuration"><a class="anchor" href="#_configuration_from_a_apache_commons_configuration"></a><a class="link" href="#_configuration_from_a_apache_commons_configuration">3.2.4. Configuration from a Apache Commons Configuration</a></h4>
|
||
<div class="paragraph">
|
||
<p>Configuration parameters may be loaded from the following sources using Apache Commons Configuration:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Properties files</p>
|
||
</li>
|
||
<li>
|
||
<p>XML documents</p>
|
||
</li>
|
||
<li>
|
||
<p>Property list files (plist)</p>
|
||
</li>
|
||
<li>
|
||
<p>JDBC Datasource</p>
|
||
</li>
|
||
<li>
|
||
<p>Servlet parameters</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Configurations configs = <span class="keyword">new</span> Configurations();
|
||
<span class="predefined-type">Configuration</span> configuration = configs.properties(<span class="string"><span class="delimiter">"</span><span class="content">config.properties</span><span class="delimiter">"</span></span>); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
Swagger2MarkupConfig config = <span class="keyword">new</span> Swagger2MarkupConfigBuilder(configuration) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.build();
|
||
|
||
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.withConfig(config)
|
||
.build();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create an Apache Commons <code>Configuration</code> object using the proper ConfigurationBuilder.</p>
|
||
</li>
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupConfigBuilder</code> using the proper constructor.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_swagger2markup_properties"><a class="anchor" href="#_swagger2markup_properties"></a><a class="link" href="#_swagger2markup_properties">3.2.5. Swagger2Markup properties</a></h4>
|
||
<div class="paragraph">
|
||
<p>The properties of Swagger2Markup are defined in the class <code>io.github.swagger2markup.Swagger2MarkupProperties</code>.<br>
|
||
The properties are considered in the following order:</p>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Java System properties</p>
|
||
</li>
|
||
<li>
|
||
<p>Custom properties</p>
|
||
</li>
|
||
<li>
|
||
<p>Default properties (included in Swagger2Markup)</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following tables list all available properties of Swagger2Markup:</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 1. Mostly used properties</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.markupLanguage</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the markup language which should be used to generate the files.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">ASCIIDOC</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.swaggerMarkupLanguage</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the markup language used in Swagger descriptions.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">MARKDOWN</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.pathsGroupedBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how the paths should be grouped</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, TAGS, REGEX</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.outputLanguage</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the language of the labels</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">EN, DE, FR, RU</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">EN</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.lineSeparator</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the line separator which should be used</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">UNIX, WINDOWS, MAC</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><System-dependent></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.generatedExamplesEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies if HTTP request and response examples should be generated</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.flatBodyEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Optionally isolate the body parameter, if any, from other parameters</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.pathSecuritySectionEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Optionally disable the security section for path sections</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.anchorPrefix</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Optionally prefix all anchors for uniqueness if you want to include generated documents into a global documentation</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.basePathPrefixEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Prepend the basePath to all paths</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.headerRegex</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Regular expression to use when grouping by RegEx</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any valid RegEx pattern with at least one capture group</p></td>
|
||
<td class="tableblock halign-left valign-top"></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 2. Properties which configure the order of Swagger Objects</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.tagOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of global tags</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.operationOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of path operations</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.definitionOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of definitions</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.parameterOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of operation parameters</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.propertyOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of definition properties</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.responseOrderBy</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the order of responses</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">AS_IS, NATURAL, CUSTOM</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">NATURAL</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 3. Properties which configure document file names</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.overviewDocument</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the file name of the overview document</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"overview"</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.pathsDocument</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the file name of the paths document</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"paths"</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.definitionsDocument</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the file name of the definitions document</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"definitions"</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.securityDocument</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the file name of the security document</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"security"</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 4. Properties which configure the generation of separate files</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.separatedDefinitionsEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">In addition to the Definitions file, also create separate definition files for each model definition</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.separatedOperationsEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">In addition to the Paths file, also create separate operation files for each operation</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.separatedOperationsFolder</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the target folder path for definition files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any valid folder name</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"operations"</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.separatedDefinitionsFolder</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the target folder path for operation files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any valid folder name</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">"definitions"</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 5. Properties which configure inter-document cross references</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.interDocumentCrossReferencesEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Enable use of inter-document cross-references when needed</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.interDocumentCrossReferencesPrefix</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies a prefix for all inter-document cross-references for advanced usage</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Any String</p></td>
|
||
<td class="tableblock halign-left valign-top"></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 6. Properties which configure inline schema rendering</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.inlineSchemaEnabled</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Enable inline object schema support</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true, false</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 7. Properties which configure page breaking</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Possible Values</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swagger2markup.pageBreakLocations</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies where page breaks should be inserted.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">BEFORE_OPERATION, BEFORE_OPERATION_DESCRIPTION, BEFORE_OPERATION_PARAMETERS, BEFORE_OPERATION_RESPONSES, BEFORE_OPERATION_CONSUMES, BEFORE_OPERATION_PRODUCES, BEFORE_OPERATION_EXAMPLE_REQUEST, BEFORE_OPERATION_EXAMPLE_RESPONSE, BEFORE_DEFINITION, AFTER_OPERATION, AFTER_OPERATION_DESCRIPTION, AFTER_OPERATION_PARAMETERS, AFTER_OPERATION_RESPONSES, AFTER_OPERATION_CONSUMES, AFTER_OPERATION_PRODUCES, AFTER_OPERATION_EXAMPLE_REQUEST, AFTER_OPERATION_EXAMPLE_RESPONSE, AFTER_DEFINITION</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">empty</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_logging"><a class="anchor" href="#_logging"></a><a class="link" href="#_logging">3.3. Logging</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup uses <a href="http://www.slf4j.org/">SLF4J</a> for all internal logging, but leaves the underlying log implementation open. To change the log level, you have the set the log level of the <code>io.github.swagger2markup</code> package.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_advanced_usage"><a class="anchor" href="#_advanced_usage"></a><a class="link" href="#_advanced_usage">4. Advanced usage</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="sect2">
|
||
<h3 id="swagger_operationId"><a class="anchor" href="#swagger_operationId"></a><a class="link" href="#swagger_operationId">4.1. Swagger operationId</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup uniquely identify each operations for multiple purposes :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>generating separated operation files : file name</p>
|
||
</li>
|
||
<li>
|
||
<p>generating unique Markup anchors for operations and all sub-items.</p>
|
||
</li>
|
||
<li>
|
||
<p>searching for extra content for operations : operation folder name for content plugins (Hand-written descriptions, Dynamic content, etc…​)</p>
|
||
</li>
|
||
<li>
|
||
<p>…​</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Swagger specification supports the <code>operationId</code> field which create an unique name for each operation.<br>
|
||
When provided, this <code>operationId</code> value will be used primarily. Otherwise Swagger2Markup generates an id using <code>normalize(operation.summary + " " + lowerCase(operation.HTTPmethod))</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock important">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-important" title="Important"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is highly recommended to set an operationId for each operation, so that a lot of actions does not depend on operation <code>summary</code> which <strong>can change at anytime</strong>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_swagger_schema_title"><a class="anchor" href="#_swagger_schema_title"></a><a class="link" href="#_swagger_schema_title">4.2. Swagger schema title</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup displays inline schemas by decomposing them (when schema is complex). In this process, some intermediate references are generated using field names which is not always the best choice.<br>
|
||
The Swagger document supports JSON Schema <code>title</code> items in inline schemas.<br>
|
||
It’s recommended to use them in inline schemas so that they’ll be used primarily to field names and this will lead to a better naming.</p>
|
||
</div>
|
||
<div class="exampleblock">
|
||
<div class="title">Example 1. Inline schema without title items</div>
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="yaml"> InlinePet:
|
||
type: object
|
||
required:
|
||
- id
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
category:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
tags:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="images/untitledSwagger.png" alt="untitledSwagger">
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="exampleblock">
|
||
<div class="title">Example 2. Inline schema with title items</div>
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="yaml"> InlineTitlePet:
|
||
type: object
|
||
required:
|
||
- id
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
category:
|
||
type: object
|
||
<strong>title: CategoryModel</strong>
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
tags:
|
||
type: array
|
||
items:
|
||
type: object
|
||
<strong>title: TagModel</strong>
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="images/titledSwagger.png" alt="titledSwagger">
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_extension_spi"><a class="anchor" href="#_extension_spi"></a><a class="link" href="#_extension_spi">5. Extension SPI</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2Markup. Five types of extension are available. An extension is an abstract class which must be implemented.</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 8. Swagger2Markup extensions</caption>
|
||
<colgroup>
|
||
<col style="width: 33.3333%;">
|
||
<col style="width: 33.3333%;">
|
||
<col style="width: 33.3334%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Class</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_overviewdocumentextension">OverviewDocumentExtension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">io.github.swagger2markup.spi.OverviewDocumentExtension</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be used to extend the content of the Overview document</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_pathsdocumentextension">PathsDocumentExtension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">io.github.swagger2markup.spi.PathsDocumentExtension</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be used to extend the content of the Paths document</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_securitydocumentextension">SecurityDocumentExtension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">io.github.swagger2markup.spi.SecurityDocumentExtension</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be used to extend the content of the Security document</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_definitionsdocumentextension">DefinitionsDocumentExtension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">io.github.swagger2markup.spi.DefinitionsDocumentExtension</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be used to extend the content of the Definitions document</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_swaggermodelextension">SwaggerModelExtension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">io.github.swagger2markup.spi.SwaggerModelExtension</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be used to modify the Swagger model before it is converted</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="sect2">
|
||
<h3 id="_creation_of_an_extension"><a class="anchor" href="#_creation_of_an_extension"></a><a class="link" href="#_creation_of_an_extension">5.1. Creation of an extension</a></h3>
|
||
<div class="paragraph">
|
||
<p>To create a custom extension, you have to create a class (e.g. <code>io.myname.MyExtension</code>) which extends an extension, e.g. <code>io.github.swagger2markup.spi.DefinitionsDocumentExtension</code>. Every extension point provides two methods which must be implemented:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>init</code>: This method is invoked once and can be used to initialize the extension.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>apply</code>: This method is invoked multiple times depending on the type of the extension. The <code>Position</code> can be retrieved from the <code>Context</code> and can be used to extend the document at specific extension points.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MyExtension</span> <span class="directive">extends</span> DefinitionsDocumentExtension {
|
||
|
||
<span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">String</span> EXTENSION_ID = <span class="string"><span class="delimiter">"</span><span class="content">myExtension</span><span class="delimiter">"</span></span>;
|
||
<span class="directive">private</span> <span class="predefined-type">String</span> extensionProperty;
|
||
|
||
<span class="annotation">@Override</span>
|
||
<span class="directive">public</span> <span class="type">void</span> init(Swagger2MarkupConverter.Context globalContext) {
|
||
<span class="comment">// init is executed once</span>
|
||
Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties(); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
extensionProperty = extensionProperties.getRequiredString(EXTENSION_ID + <span class="string"><span class="delimiter">"</span><span class="content">.propertyName</span><span class="delimiter">"</span></span>);
|
||
Swagger model = globalContext.getSwagger();
|
||
}
|
||
|
||
<span class="annotation">@Override</span>
|
||
<span class="directive">public</span> <span class="type">void</span> apply(<span class="predefined-type">Context</span> context) {
|
||
MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder(); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
<span class="predefined-type">Position</span> position = context.getPosition(); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
<span class="predefined-type">String</span> definitionName = context.getDefinitionName().get();
|
||
Model definitionModel = context.getModel().get();
|
||
|
||
<span class="keyword">if</span> (position.equals(<span class="predefined-type">Position</span>.DEFINITION_END)) {
|
||
markupBuilder.sectionTitleLevel1(definitionName) <i class="conum" data-value="4"></i><b>(4)</b>
|
||
.paragraph(definitionModel.getDescription())
|
||
.importMarkup(<span class="keyword">new</span> <span class="predefined-type">StringReader</span>(<span class="string"><span class="delimiter">"</span><span class="content">*Markup*</span><span class="delimiter">"</span></span>), MarkupLanguage.ASCIIDOC);
|
||
}
|
||
|
||
<span class="comment">// apply is executed per definition</span>
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>You can retrieve extension properties from the config to configure the extension.</p>
|
||
</li>
|
||
<li>
|
||
<p>You can retrieve a <code>MarkupDocBuilder</code> from the <code>Context</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>You can retrieve the current <code>Position</code> from the Context.</p>
|
||
</li>
|
||
<li>
|
||
<p>You can use a <code>MarkupDocBuilder</code> to add Markup using a fluent API or import Markup from files.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_registration_of_an_extension"><a class="anchor" href="#_registration_of_an_extension"></a><a class="link" href="#_registration_of_an_extension">5.2. Registration of an extension</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup extensions must be registered in the <code>Swagger2MarkupExtensionRegistry</code>. The default <code>Swagger2MarkupExtensionRegistry</code> of Swagger2Markup uses the <code>java.util.ServiceLoader</code> to load and register Swagger2Markup extensions automatically.</p>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_automatic_registration"><a class="anchor" href="#_automatic_registration"></a><a class="link" href="#_automatic_registration">5.2.1. Automatic registration</a></h4>
|
||
<div class="paragraph">
|
||
<p>To register your extension automatically, the following steps are required:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Create a file called <code>META-INF/services/io.github.swagger2markup.spi.DefinitionsDocumentExtension</code> which contains your extensions’s full qualified name, e.g. <code>io.myname.MyExtension</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>When a <code>.jar</code> file containing your extension is added to the classpath of Swagger2Markup, the extensions will be automatically registered.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_manual_registration"><a class="anchor" href="#_manual_registration"></a><a class="link" href="#_manual_registration">5.2.2. Manual registration</a></h4>
|
||
<div class="paragraph">
|
||
<p>To register your extension manually, you have to use the <code>Swagger2MarkupExtensionRegistryBuilder</code>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">Swagger2MarkupExtensionRegistry registry = <span class="keyword">new</span> Swagger2MarkupExtensionRegistryBuilder() <i class="conum" data-value="1"></i><b>(1)</b>
|
||
.withDefinitionsDocumentExtension(<span class="keyword">new</span> MyExtension()) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
.build(); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
|
||
.withExtensionRegistry(registry) <i class="conum" data-value="4"></i><b>(4)</b>
|
||
.build();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Create a <code>Swagger2MarkupExtensionRegistryBuilder</code> using the default constructor</p>
|
||
</li>
|
||
<li>
|
||
<p>Register your custom extension</p>
|
||
</li>
|
||
<li>
|
||
<p>Build an instance of <code>Swagger2MarkupExtensionRegistry</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Use the custom Swagger2MarkupExtensionRegistry</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_extensions_points"><a class="anchor" href="#_extensions_points"></a><a class="link" href="#_extensions_points">5.3. Extensions points</a></h3>
|
||
<div class="sect3">
|
||
<h4 id="_overviewdocumentextension"><a class="anchor" href="#_overviewdocumentextension"></a><a class="link" href="#_overviewdocumentextension">5.3.1. OverviewDocumentExtension</a></h4>
|
||
<div class="paragraph">
|
||
<p>The OverviewDocumentExtension allows to extend the overview document at positions :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DOCUMENT_BEFORE: Before the document title (title level offset = 0)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_BEGIN: After the document title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_END: At the end of the document (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_AFTER: At the very end of the document (title level offset = 0)</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Extension content titles must always start from level <strong>1</strong>. The title level will be adapted depending on position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_pathsdocumentextension"><a class="anchor" href="#_pathsdocumentextension"></a><a class="link" href="#_pathsdocumentextension">5.3.2. PathsDocumentExtension</a></h4>
|
||
<div class="paragraph">
|
||
<p>The PathsDocumentExtension allows to extend the paths document at positions :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DOCUMENT_BEFORE: Before the document title (title level offset = 0)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_BEGIN: After the document title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_BEFORE: Before each operation title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_BEGIN: After each operation title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_END: At the end of each operation (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_AFTER: At the very end of each operation (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_END: At the end of the document (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_AFTER: At the very end of the document (title level offset = 0)</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Moreover, the PathsDocumentExtension allows to extend operation sections at positions :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_BEFORE: Before each description section title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_BEGIN: After each description section title (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_END: At the end of each description section (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_AFTER: At the very end of each description section (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_BEFORE: Before each parameters section title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_BEGIN: After each parameters section title (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_END: At the end of each parameters section (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_AFTER: At the very end of each parameters section (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_BEFORE: Before each responses section title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_BEGIN: After each responses section title (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_END: At the end of each responses section (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_AFTER: At the very end of each responses section (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_BEFORE: Before each security section title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_BEGIN: After each security section title (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_END: At the end of each security section (title level offset = 3)</p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_AFTER: At the very end of each security section (title level offset = 2)</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Extension content titles must always start from level <strong>1</strong>. The title level will be adapted depending on position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_securitydocumentextension"><a class="anchor" href="#_securitydocumentextension"></a><a class="link" href="#_securitydocumentextension">5.3.3. SecurityDocumentExtension</a></h4>
|
||
<div class="paragraph">
|
||
<p>The SecurityDocumentExtension allows to extend the security document at positions :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DOCUMENT_BEFORE: Before the document title (title level offset = 0)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_BEGIN: After the document title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_BEFORE: Before each security scheme title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_BEGIN: After each security scheme title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_END: At the end of each security scheme (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_AFTER: At the very end of each security scheme (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_END: At the end of the document (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_AFTER: At the very end of the document (title level offset = 0)</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Extension content titles must always start from level <strong>1</strong>. The title level will be adapted depending on position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_definitionsdocumentextension"><a class="anchor" href="#_definitionsdocumentextension"></a><a class="link" href="#_definitionsdocumentextension">5.3.4. DefinitionsDocumentExtension</a></h4>
|
||
<div class="paragraph">
|
||
<p>The DefinitionsDocumentExtension allows to extend the definitions document at positions :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DOCUMENT_BEFORE: Before the document title (title level offset = 0)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_BEGIN: After the document title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_BEFORE: Before each definition title (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_BEGIN: After each definition title (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_END: At the end of each definition (title level offset = 2)</p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_AFTER: At the very end of each definition (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_END: At the end of the document (title level offset = 1)</p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_AFTER: At the very end of the document (title level offset = 0)</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Extension content titles must always start from level <strong>1</strong>. The title level will be adapted depending on position.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_swaggermodelextension"><a class="anchor" href="#_swaggermodelextension"></a><a class="link" href="#_swaggermodelextension">5.3.5. SwaggerModelExtension</a></h4>
|
||
<div class="paragraph">
|
||
<p>The SwaggerModelExtension allows to modify the Swagger model before it is processed by Swagger2Markup. For example, you could use this extension to delete Paths from the Swagger model which should not be rendered.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Example:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MySwaggerModelExtension</span> <span class="directive">extends</span> SwaggerModelExtension {
|
||
|
||
<span class="directive">public</span> <span class="type">void</span> apply(Swagger swagger) {
|
||
swagger.setHost(<span class="string"><span class="delimiter">"</span><span class="content">newHostName</span><span class="delimiter">"</span></span>); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
swagger.basePath(<span class="string"><span class="delimiter">"</span><span class="content">newBasePath</span><span class="delimiter">"</span></span>);
|
||
|
||
<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, Path> paths = swagger.getPaths(); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
paths.remove(<span class="string"><span class="delimiter">"</span><span class="content">/remove</span><span class="delimiter">"</span></span>);
|
||
swagger.setPaths(paths);
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>You can change any Swagger model property</p>
|
||
</li>
|
||
<li>
|
||
<p>You could even remove elements from the Swagger model</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="extension_commons_content_markup"><a class="anchor" href="#extension_commons_content_markup"></a><a class="link" href="#extension_commons_content_markup">5.4. Content markup language</a></h3>
|
||
<div class="paragraph">
|
||
<p>Most content extensions supports to provide content in any markup language which will be <strong>converted, if needed, to configured Swagger2Markup converter markup language</strong> at import.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The content files markup language can be any <a href="https://github.com/Swagger2Markup/markup-document-builder">markup-document-builder</a> supported language :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>ASCIIDOC : AsciiDoc. Mandatory content file extension : <code>adoc</code></p>
|
||
</li>
|
||
<li>
|
||
<p>MARKDOWN : Github Flavored Markdown. Mandatory content file extension : <code>md</code></p>
|
||
</li>
|
||
<li>
|
||
<p>CONFLUENCE_MARKUP : Confluence Wiki markup. Mandatory content file extension : <code>txt</code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock important">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-important" title="Important"></i>
|
||
</td>
|
||
<td class="content">
|
||
<div class="paragraph">
|
||
<p>Currently supported conversions are :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Markdown → AsciiDoc</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_provided_extensions"><a class="anchor" href="#_provided_extensions"></a><a class="link" href="#_provided_extensions">5.5. Provided Extensions</a></h3>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides some extensions which can be used out-of-the-box. You just have to add the extension to your classpath.</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 9. Swagger2Markup extensions</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#extension_import_files">Dynamic file import extension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to dynamically import Markup from files.</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#extension_spring_restdocs">Spring RestDocs extension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to import Curl, HTTP request and response snippets from <a href="https://github.com/spring-projects/spring-restdocs">Spring Rest Docs</a>.</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#extension_import_schemas">Schema file import extension</a></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows to import JSON or XML Schema files.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="sect3">
|
||
<h4 id="extension_import_files"><a class="anchor" href="#extension_import_files"></a><a class="link" href="#extension_import_files">5.5.1. Dynamic file import extension</a></h4>
|
||
<div class="sect4">
|
||
<h5 id="_usage_guide_2"><a class="anchor" href="#_usage_guide_2"></a><a class="link" href="#_usage_guide_2">Usage guide</a></h5>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">repositories {
|
||
jCenter()
|
||
}
|
||
|
||
compile "io.github.swagger2markup:swagger2markup-import-files-ext:1.3.2-SNAPSHOT"</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The extension searches for markup files in configurable paths to append the markup to the documents at supported positions.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The markup files must conform to a naming convention to be found. The files must start with the position where the document should be extended and end with the markup file extension (e.g <code>adoc</code> or <code>md</code>).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>See documentation of <a href="#_extensions_points">Extensions points</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Here the list of all document naming conventions for each position. You have to replace <code>*</code> with an arbitrary, meaningful, identifier.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
You can provide multiple contents for the same position, just specify different identifiers in place of <code>*</code> in the file name. The concurrent contents for a given position will all be added to the document in a determinist order, sorting content file by natural order.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>All extensions, relatively to each extension contentPath :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DOCUMENT_BEFORE : <code>document-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_BEGIN : <code>document-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_END : <code>document-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DOCUMENT_AFTER : <code>document-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Paths extensions, relatively to each extension contentPath :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>OPERATION_BEFORE : <code><a href="#swagger_operationId"><operationId></a>/operation-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_BEGIN : <code><a href="#swagger_operationId"><operationId></a>/operation-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_END : <code><a href="#swagger_operationId"><operationId></a>/operation-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_AFTER : <code><a href="#swagger_operationId"><operationId></a>/operation-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_BEFORE: <code><a href="#swagger_operationId"><operationId></a>/operation-description-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_BEGIN: <code><a href="#swagger_operationId"><operationId></a>/operation-description-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_END: <code><a href="#swagger_operationId"><operationId></a>/operation-description-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_DESCRIPTION_AFTER: <code><a href="#swagger_operationId"><operationId></a>/operation-description-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_BEFORE: <code><a href="#swagger_operationId"><operationId></a>/operation-parameters-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_BEGIN: <code><a href="#swagger_operationId"><operationId></a>/operation-parameters-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_END: <code><a href="#swagger_operationId"><operationId></a>/operation-parameters-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_PARAMETERS_AFTER: <code><a href="#swagger_operationId"><operationId></a>/operation-parameters-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_BEFORE: <code><a href="#swagger_operationId"><operationId></a>/operation-responses-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_BEGIN: <code><a href="#swagger_operationId"><operationId></a>/operation-responses-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_END: <code><a href="#swagger_operationId"><operationId></a>/operation-responses-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_RESPONSES_AFTER: <code><a href="#swagger_operationId"><operationId></a>/operation-responses-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_BEFORE: <code><a href="#swagger_operationId"><operationId></a>/operation-security-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_BEGIN: <code><a href="#swagger_operationId"><operationId></a>/operation-security-begin*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_END: <code><a href="#swagger_operationId"><operationId></a>/operation-security-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>OPERATION_SECURITY_AFTER: <code><a href="#swagger_operationId"><operationId></a>/operation-security-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Definitions extensions, relatively to each extension contentPath :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>DEFINITION_BEFORE : <code><definitionName>/definition-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_BEGIN : <code><definitionName>/definition-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_END : <code><definitionName>/definition-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>DEFINITION_AFTER : <code><definitionName>/definition-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Security extensions, relatively to each extension contentPath :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>SECURITY_SCHEME_BEFORE : <code><securitySchemeName>/security-scheme-before-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_BEGIN : <code><securitySchemeName>/security-scheme-begin-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_END : <code><securitySchemeName>/security-scheme-end-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p>SECURITY_SCHEME_AFTER : <code><securitySchemeName>/security-scheme-after-*.<a href="#extension_import_files_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock important">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-important" title="Important"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code><operationId></code> value depends on Swagger specification. If you provided an <code>operationId</code> for operations in the Swagger document, the value will be used primarily. <strong>It is highly recommended to set operationId for operations</strong> : see <a href="#swagger_operationId">Swagger operationId</a>. In all cases, all placeholder values are case-sensitive.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
It’s <strong>highly recommended</strong> to configure a different contentPath for each extension (dynamicOverview, dynamicDefinitions, etc…​) because content files for DOCUMENT_* positions have the same naming convention.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="exampleblock">
|
||
<div class="title">Example 3. Example of provided content files for petstore Swagger sample</div>
|
||
<div class="content">
|
||
<div class="literalblock">
|
||
<div class="content">
|
||
<pre>overview/document-before-intro.adoc <i class="conum" data-value="1"></i><b>(1)</b>
|
||
paths/document-before-intro.adoc <i class="conum" data-value="2"></i><b>(2)</b>
|
||
paths/updatePet/operation-begin-description.adoc
|
||
paths/updatePet/operation-end-example1.adoc
|
||
paths/updatePet/operation-end-example2.adoc <i class="conum" data-value="3"></i><b>(3)</b>
|
||
definitions/Pet/definition-begin-description.adoc</pre>
|
||
</div>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>"overview", "paths" and "definitions" are different configured contentPath for different extensions.</p>
|
||
</li>
|
||
<li>
|
||
<p>the document name is the same but will be used only in Paths document because contentPath is different (cf 1.).</p>
|
||
</li>
|
||
<li>
|
||
<p>both example1 and example2 content files will be added to "updatePet" operation. They’ll be applied consecutively, with their names sorted by natural order.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="extension_import_files_markup"><a class="anchor" href="#extension_import_files_markup"></a><a class="link" href="#extension_import_files_markup">Content markup language</a></h5>
|
||
<div class="paragraph">
|
||
<p>See <a href="#extension_commons_content_markup">Extensions content markup language</a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>By default, the markup language is set to <strong>ASCIIDOC</strong>. Set extension <a href="#extension_import_files_configuration">Configuration</a> to change content markup language.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="extension_import_files_configuration"><a class="anchor" href="#extension_import_files_configuration"></a><a class="link" href="#extension_import_files_configuration">Configuration</a></h5>
|
||
<div class="paragraph">
|
||
<p>The extension adds the following properties to Swagger2Markup which must be configured:</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 10. Extension properties</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
<th class="tableblock halign-left valign-top">Example</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicOverview.contentPath</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the files which should be imported</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/overview</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicOverview.markupLanguage</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The markup language of the content files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ASCIIDOC</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MARKDOWN</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicDefinitions.contentPath</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the files which should be imported</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/definitions</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicDefinitions.markupLanguage</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The markup language of the content files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ASCIIDOC</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MARKDOWN</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicPaths.contentPath</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the files which should be imported</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/paths</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicPaths.markupLanguage</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The markup language of the content files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ASCIIDOC</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MARKDOWN</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicSecurity.contentPath</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">TThe path to the files which should be imported</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/security</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.dynamicSecurity.markupLanguage</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The markup language of the content files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ASCIIDOC</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MARKDOWN</code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="extension_spring_restdocs"><a class="anchor" href="#extension_spring_restdocs"></a><a class="link" href="#extension_spring_restdocs">5.5.2. Spring RestDocs extension</a></h4>
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup can be used together with <a href="https://github.com/spring-projects/spring-restdocs">spring-restdocs</a>. Swagger2Markup can include the generated CURL request, HTTP request and HTTP response example snippets from spring-restdocs into the generated Markup documents. See spring-restdocs how to configure it.</p>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="_usage_guide_3"><a class="anchor" href="#_usage_guide_3"></a><a class="link" href="#_usage_guide_3">Usage guide</a></h5>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">repositories {
|
||
jCenter()
|
||
}
|
||
|
||
compile "io.github.swagger2markup:swagger2markup-spring-restdocs-ext:1.3.2-SNAPSHOT"</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The extension searches for <a href="https://github.com/spring-projects/spring-restdocs">Spring RestDocs</a> snippet files in a configurable path to append the snippets at the end of a path operation section. By default the following snippets are searched :</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code><a href="#swagger_operationId"><operationId></a>/http-request.<a href="#extension_spring_restdocs_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p><code><a href="#swagger_operationId"><operationId></a>/http-response.<a href="#extension_spring_restdocs_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
<li>
|
||
<p><code><a href="#swagger_operationId"><operationId></a>/curl-request.<a href="#extension_spring_restdocs_markup"><markup.ext></a></code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock important">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-important" title="Important"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code><operationId></code> value depends on Swagger specification. If you provided an <code>operationId</code> for operations in the Swagger document, the value will be used primarily. <strong>It is highly recommended to set operationId for operations</strong> : see <a href="#swagger_operationId">Swagger operationId</a>. In all cases, <code><operationId></code> is case-sensitive.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Swagger Example:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">paths</span>:
|
||
<span class="key">/pets</span>:
|
||
<span class="key">post</span>:
|
||
<span class="key">summary</span>: <span class="string"><span class="content">Add a new pet to the store</span></span>
|
||
<span class="key">operationId</span>: <span class="string"><span class="content">addPet</span></span>
|
||
<span class="error">...</span></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following Unit Test uses Spring RestDocs to tests the <code>/pets</code> endoint and writes the example files into the <code>build/snippets</code> folder. Have a look at the <a href="#_spring_boot_and_springfox">Spring Boot and Springfox</a> chapter for a full example using <a href="https://github.com/spring-projects/spring-boot">Spring Boot</a>, <a href="https://github.com/springfox/springfox">Springfox</a> and Spring RestDocs.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Rule</span>
|
||
<span class="directive">public</span> <span class="directive">final</span> RestDocumentation restDocumentation = <span class="keyword">new</span> RestDocumentation(<span class="string"><span class="delimiter">"</span><span class="content">build/snippets</span><span class="delimiter">"</span></span>);
|
||
|
||
<span class="annotation">@Test</span>
|
||
<span class="directive">public</span> <span class="type">void</span> addAPetToTheStore() <span class="directive">throws</span> <span class="exception">Exception</span> {
|
||
<span class="local-variable">this</span>.mockMvc.perform(post(<span class="string"><span class="delimiter">"</span><span class="content">/pets/</span><span class="delimiter">"</span></span>).content(createPet())
|
||
.contentType(MediaType.APPLICATION_JSON))
|
||
.andDo(document(<span class="string"><span class="delimiter">"</span><span class="content">addPet</span><span class="delimiter">"</span></span>, preprocessResponse(prettyPrint())))
|
||
.andExpect(status().isOk());
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Example: <code>build/snippets/addPet/http-request.adoc</code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="extension_spring_restdocs_markup"><a class="anchor" href="#extension_spring_restdocs_markup"></a><a class="link" href="#extension_spring_restdocs_markup">Content markup language</a></h5>
|
||
<div class="paragraph">
|
||
<p>See <a href="#extension_commons_content_markup">Extensions content markup language</a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>By default, the markup language is set to <strong>ASCIIDOC</strong>. Set extension <a href="#extension_spring_restdocs_configuration">Configuration</a> to change content markup language.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="extension_spring_restdocs_configuration"><a class="anchor" href="#extension_spring_restdocs_configuration"></a><a class="link" href="#extension_spring_restdocs_configuration">Configuration</a></h5>
|
||
<div class="paragraph">
|
||
<p>The extension adds the following properties to Swagger2Markup which must be configured:</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 11. Extension properties</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Default</th>
|
||
<th class="tableblock halign-left valign-top">Example</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.springRestDocs.snippetBaseUri</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the Spring RestDocs snippets</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/paths</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.springRestDocs.markupLanguage</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The markup language of the content files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ASCIIDOC</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>MARKDOWN</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.springRestDocs.defaultSnippets</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean value. Set to false to disable default snippet files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="extension_import_schemas"><a class="anchor" href="#extension_import_schemas"></a><a class="link" href="#extension_import_schemas">5.5.3. Schema file import extension</a></h4>
|
||
<div class="sect4">
|
||
<h5 id="_usage_guide_4"><a class="anchor" href="#_usage_guide_4"></a><a class="link" href="#_usage_guide_4">Usage guide</a></h5>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">repositories {
|
||
jCenter()
|
||
}
|
||
|
||
compile "io.github.swagger2markup:swagger2markup-import-schemas-ext:1.3.2-SNAPSHOT"</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The extension searches for Schema files in a configurable path to append the Schema file content at the end of a definition section. The Schema files must conform to a naming convention to be found. The files must be called <code>schema.xsd</code> or <code>schema.json</code> and must be stored in a folder which matches the name of a definition.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Example: <code>/schemas/Pet/schema.json</code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect4">
|
||
<h5 id="_configuration_2"><a class="anchor" href="#_configuration_2"></a><a class="link" href="#_configuration_2">Configuration</a></h5>
|
||
<div class="paragraph">
|
||
<p>The extension adds the following properties to Swagger2Markup which must be configured:</p>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 12. Extension properties</caption>
|
||
<colgroup>
|
||
<col style="width: 33.3333%;">
|
||
<col style="width: 33.3333%;">
|
||
<col style="width: 33.3334%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Example</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>swagger2markup.extensions.schema.schemaBaseUri</code></p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the schema files</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>src/test/resources/docs/asciidoc/schemas</code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_gradle_plugin"><a class="anchor" href="#_gradle_plugin"></a><a class="link" href="#_gradle_plugin">6. Gradle Plugin</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides a Gradle plugin. The Gradle plugin is published in JCenter and Maven Central.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The Gradle Plugin requires at least JDK 8.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_usage_guide_5"><a class="anchor" href="#_usage_guide_5"></a><a class="link" href="#_usage_guide_5">6.1. Usage guide</a></h3>
|
||
<div class="paragraph">
|
||
<p>Add the following snippet to your Gradle build file:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">buildscript {
|
||
repositories {
|
||
jcenter()
|
||
maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
|
||
}
|
||
|
||
dependencies {
|
||
classpath 'io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.1'
|
||
}
|
||
}
|
||
|
||
apply plugin: 'io.github.swagger2markup'</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The plugin adds a new task named <code>convertSwagger2markup</code>. You can run the task as follows:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>gradlew convertSwagger2markup</code></p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_configuration_3"><a class="anchor" href="#_configuration_3"></a><a class="link" href="#_configuration_3">6.2. Configuration</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can customize the task by configuring a Map of <a href="#_swagger2markup_properties">Swagger2Markup properties</a>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="groovy">convertSwagger2markup {
|
||
swaggerInput file(<span class="string"><span class="delimiter">"</span><span class="content">src/docs/swagger/swagger_petstore.yaml</span><span class="delimiter">"</span></span>).getAbsolutePath()
|
||
outputDir file(<span class="string"><span class="delimiter">"</span><span class="inline"><span class="inline-delimiter">${</span>buildDir<span class="inline-delimiter">}</span></span><span class="content">/asciidoc</span><span class="delimiter">"</span></span>)
|
||
config = [<span class="string"><span class="delimiter">'</span><span class="content">swagger2markup.markupLanguage</span><span class="delimiter">'</span></span> : <span class="string"><span class="delimiter">'</span><span class="content">ASCIIDOC</span><span class="delimiter">'</span></span>,
|
||
<span class="string"><span class="delimiter">'</span><span class="content">swagger2markup.pathsGroupedBy</span><span class="delimiter">'</span></span> : <span class="string"><span class="delimiter">'</span><span class="content">TAGS</span><span class="delimiter">'</span></span>]
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 13. Gradle Plugin properties</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Type</th>
|
||
<th class="tableblock halign-left valign-top">Example</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swaggerInput</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The URL or file path to the Swagger specification</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>file("src/docs/swagger/swagger_petstore.yaml").getAbsolutePath()</code> or <code><a href="http://petstore.swagger.io/v2/swagger.json" class="bare">http://petstore.swagger.io/v2/swagger.json</a></code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">outputDir</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory where the output should be stored.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">File</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>file("${buildDir}/asciidoc")</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">outputFile</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The file path (without extension) where the output should be stored.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">File</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>file("${buildDir}/asciidoc/swagger")</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">config</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The Swagger2Markup properties to configure the converter</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Map</p></td>
|
||
<td class="tableblock halign-left valign-top"></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_example"><a class="anchor" href="#_example"></a><a class="link" href="#_example">6.3. Example</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can copy the template project from GitHub to get started.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><a href="https://github.com/Swagger2Markup/swagger2markup-gradle-project-template" class="bare">https://github.com/Swagger2Markup/swagger2markup-gradle-project-template</a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_maven_plugin"><a class="anchor" href="#_maven_plugin"></a><a class="link" href="#_maven_plugin">7. Maven Plugin</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides a Maven plugin. The Maven plugin is published in JCenter and Maven Central.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The Maven Plugin requires at least JDK 8.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_usage_guide_6"><a class="anchor" href="#_usage_guide_6"></a><a class="link" href="#_usage_guide_6">7.1. Usage guide</a></h3>
|
||
<div class="paragraph">
|
||
<p>Add the following snippet to your Maven POM file:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><pluginRepositories></span>
|
||
<span class="tag"><pluginRepository></span>
|
||
<span class="tag"><id></span>jcenter-snapshots<span class="tag"></id></span>
|
||
<span class="tag"><name></span>jcenter<span class="tag"></name></span>
|
||
<span class="tag"><url></span>http://oss.jfrog.org/artifactory/oss-snapshot-local/<span class="tag"></url></span>
|
||
<span class="tag"></pluginRepository></span>
|
||
<span class="tag"><pluginRepository></span>
|
||
<span class="tag"><snapshots></span>
|
||
<span class="tag"><enabled></span>false<span class="tag"></enabled></span>
|
||
<span class="tag"></snapshots></span>
|
||
<span class="tag"><id></span>jcenter-releases<span class="tag"></id></span>
|
||
<span class="tag"><name></span>jcenter<span class="tag"></name></span>
|
||
<span class="tag"><url></span>http://jcenter.bintray.com<span class="tag"></url></span>
|
||
<span class="tag"></pluginRepository></span>
|
||
<span class="tag"></pluginRepositories></span>
|
||
|
||
<span class="tag"><build></span>
|
||
<span class="tag"><plugins></span>
|
||
<span class="tag"><plugin></span>
|
||
<span class="tag"><groupId></span>io.github.swagger2markup<span class="tag"></groupId></span>
|
||
<span class="tag"><artifactId></span>swagger2markup-maven-plugin<span class="tag"></artifactId></span>
|
||
<span class="tag"><version></span>1.3.1<span class="tag"></version></span>
|
||
<span class="tag"></plugin></span>
|
||
<span class="tag"></plugins></span>
|
||
<span class="tag"></build></span></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The plugin adds a new task goal <code>swagger2markup:convertSwagger2markup</code>. You can run the goal as follows:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>mvn swagger2markup:convertSwagger2markup</code></p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_configuration_4"><a class="anchor" href="#_configuration_4"></a><a class="link" href="#_configuration_4">7.2. Configuration</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can customize the task by configuring a Map of <a href="#_swagger2markup_properties">Swagger2Markup properties</a>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><build></span>
|
||
<span class="tag"><plugins></span>
|
||
<span class="tag"><plugin></span>
|
||
<span class="tag"><groupId></span>io.github.swagger2markup<span class="tag"></groupId></span>
|
||
<span class="tag"><artifactId></span>swagger2markup-maven-plugin<span class="tag"></artifactId></span>
|
||
<span class="tag"><version></span>1.3.1<span class="tag"></version></span>
|
||
<span class="tag"><configuration></span>
|
||
<span class="tag"><swaggerInput></span>${project.basedir}/src/docs/swagger/swagger_petstore.yaml<span class="tag"></swaggerInput></span>
|
||
<span class="tag"><outputDir></span>${project.build.directory}/asciidoc<span class="tag"></outputDir></span>
|
||
<span class="tag"><config></span>
|
||
<span class="tag"><swagger2markup.markupLanguage></span>ASCIIDOC<span class="tag"></swagger2markup.markupLanguage></span>
|
||
<span class="tag"></config></span>
|
||
<span class="tag"></configuration></span>
|
||
<span class="tag"></plugin></span>
|
||
<span class="tag"></plugins></span>
|
||
<span class="tag"></build></span></code></pre>
|
||
</div>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all spread">
|
||
<caption class="title">Table 14. Maven Plugin properties</caption>
|
||
<colgroup>
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
<col style="width: 25%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Name</th>
|
||
<th class="tableblock halign-left valign-top">Description</th>
|
||
<th class="tableblock halign-left valign-top">Type</th>
|
||
<th class="tableblock halign-left valign-top">Example</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">swaggerInput</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The URL or file path to the Swagger specification</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${project.basedir}/src/docs/swagger/swagger_petstore.yaml</code> or <code><a href="http://petstore.swagger.io/v2/swagger.json" class="bare">http://petstore.swagger.io/v2/swagger.json</a></code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">outputDir</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory where the output should be stored.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">File</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${project.build.directory}/asciidoc</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">outputFile</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The file path (without extension) where the output should be stored.</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">File</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${project.build.directory}/asciidoc/swagger</code></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">config</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">The Swagger2Markup properties to configure the converter</p></td>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock">Map</p></td>
|
||
<td class="tableblock halign-left valign-top"></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_example_2"><a class="anchor" href="#_example_2"></a><a class="link" href="#_example_2">7.3. Example</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can copy the template project from GitHub to get started.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><a href="https://github.com/Swagger2Markup/swagger2markup-maven-project-template" class="bare">https://github.com/Swagger2Markup/swagger2markup-maven-project-template</a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_command_line_interface"><a class="anchor" href="#_command_line_interface"></a><a class="link" href="#_command_line_interface">8. Command Line Interface</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Swagger2Markup provides a Command line interface (CLI). The CLI is published in JCenter and Maven Central. The artifacts can be viewed at the following locations:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Releases: <a href="https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/" class="bare">https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/</a></p>
|
||
</li>
|
||
<li>
|
||
<p>Snapshots: <a href="https://oss.jfrog.org/artifactory/oss-snapshot-local/io/github/swagger2markup/swagger2markup-cli/" class="bare">https://oss.jfrog.org/artifactory/oss-snapshot-local/io/github/swagger2markup/swagger2markup-cli/</a></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The CLI requires at least JDK 8.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_usage_guide_7"><a class="anchor" href="#_usage_guide_7"></a><a class="link" href="#_usage_guide_7">8.1. Usage guide</a></h3>
|
||
<div class="sect3">
|
||
<h4 id="_show_help"><a class="anchor" href="#_show_help"></a><a class="link" href="#_show_help">8.1.1. Show help</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can show the help:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code>java -jar swagger2markup-cli-1.3.1.jar help convert</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Output:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre>NAME
|
||
swagger2markup convert - Converts a Swagger JSON or YAML file into
|
||
Markup documents.
|
||
|
||
SYNOPSIS
|
||
swagger2markup convert [(-c <configFile> | --config <configFile>)]
|
||
[(-d <outputDir> | --outputDir <outputDir>)]
|
||
[(-f <outputFile> | --outputFile <outputFile>)]
|
||
(-i <swaggerInput> | --swaggerInput <swaggerInput>)
|
||
|
||
OPTIONS
|
||
-c <configFile>, --config <configFile>
|
||
Config file.
|
||
|
||
-d <outputDir>, --outputDir <outputDir>
|
||
Output directory. Converts the Swagger specification into multiple
|
||
files.
|
||
|
||
-f <outputFile>, --outputFile <outputFile>
|
||
Output file. Converts the Swagger specification into one file.
|
||
|
||
-h, --help
|
||
Display help information
|
||
|
||
-i <swaggerInput>, --swaggerInput <swaggerInput>
|
||
Swagger input. Can either be a URL or a file path.</pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_into_a_folder"><a class="anchor" href="#_conversion_into_a_folder"></a><a class="link" href="#_conversion_into_a_folder">8.1.2. Conversion into a folder</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert a Swagger file into a folder as follows:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code>java -jar swagger2markup-cli-1.3.1.jar convert -i /path/to/swagger_petstore.yaml -d /tmp/asiidoc</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>It generates the Markup documents into the <code>/tmp/asiidoc</code> folder.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_into_a_file_2"><a class="anchor" href="#_conversion_into_a_file_2"></a><a class="link" href="#_conversion_into_a_file_2">8.1.3. Conversion into a file</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert a local Swagger file into a file as follows:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code>java -jar swagger2markup-cli-1.3.1.jar convert -i /path/to/swagger_petstore.yaml -f /tmp/asiidoc/swagger</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The input file must not have a file extension
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>It generates the Markup documents into the file <code>/tmp/asiidoc/swagger.adoc</code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_conversion_of_a_remote_swagger_file_2"><a class="anchor" href="#_conversion_of_a_remote_swagger_file_2"></a><a class="link" href="#_conversion_of_a_remote_swagger_file_2">8.1.4. Conversion of a remote Swagger file</a></h4>
|
||
<div class="paragraph">
|
||
<p>You can convert a remote Swagger specification which must be accessible via HTTP.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code>java -jar swagger2markup-cli-1.3.1.jar convert -i "http://petstore.swagger.io/v2/swagger.json" -d /tmp</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_configuration_5"><a class="anchor" href="#_configuration_5"></a><a class="link" href="#_configuration_5">8.2. Configuration</a></h3>
|
||
<div class="paragraph">
|
||
<p>Create a <code>config.properties</code> file to customize the <a href="#_swagger2markup_properties">Swagger2Markup properties</a>. For Example:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">config.properties</div>
|
||
<div class="content">
|
||
<pre>swagger2markup.markupLanguage=MARKDOWN
|
||
swagger2markup.outputLanguage=DE</pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Invoke the CLI as follows:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code>java -jar swagger2markup-cli-1.3.1.jar convert -i /path/to/swagger_petstore.yaml -o /tmp -c /path/to/config.properties</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_docker_image"><a class="anchor" href="#_docker_image"></a><a class="link" href="#_docker_image">9. Docker image</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>The Swagger2Markup-CLI has been published as a Docker image on DockerHub.</p>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_usage_guide_8"><a class="anchor" href="#_usage_guide_8"></a><a class="link" href="#_usage_guide_8">9.1. Usage guide</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can pull the Swagger2Markup image as follows:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>docker pull swagger2markup/swagger2markup</code></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>You can convert a Swagger Spec by running a Docker container as follows:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger.yaml -f /opt/swagger -c /opt/config.properties</code></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_spring_boot_and_springfox"><a class="anchor" href="#_spring_boot_and_springfox"></a><a class="link" href="#_spring_boot_and_springfox">10. Spring Boot and Springfox</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>If you use Spring Boot and Springfox or Swagger JAX-RS, you can do the following:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>generate an up-to-date Swagger JSON file during an unit or integration test</p>
|
||
</li>
|
||
<li>
|
||
<p>convert the Swagger JSON file into AsciiDoc</p>
|
||
</li>
|
||
<li>
|
||
<p>add hand-written AsciiDoc documentation</p>
|
||
</li>
|
||
<li>
|
||
<p>convert AsciiDoc into HTML and PDF</p>
|
||
</li>
|
||
<li>
|
||
<p>copy the HTML and PDF artifacts into an executable Spring Boot Jar file and serve it as static content</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This transformation pipeline can be done with Gradle or Maven in the build phase. That way there is no runtime overhead and there are no additional runtime libraries required.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The Swagger2MarkupConverter can be used to make a request to a remote Swagger endpoint during an integration test. The Swagger2MarkupConverter allows to write the generated documents into any folder. In this this example it is <code>src/docs/asciidoc/generated</code>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@RunWith</span>(SpringJUnit4ClassRunner.class)
|
||
<span class="annotation">@SpringApplicationConfiguration</span>(classes = {Application.class, SwaggerConfig.class})
|
||
<span class="annotation">@WebIntegrationTest</span>
|
||
<span class="directive">public</span> <span class="type">class</span> <span class="class">Swagger2MarkupTest</span> {
|
||
|
||
<span class="annotation">@Test</span>
|
||
<span class="directive">public</span> <span class="type">void</span> convertRemoteSwaggerToAsciiDoc() {
|
||
<span class="comment">// Remote Swagger source</span>
|
||
Swagger2MarkupConverter.from(<span class="keyword">new</span> <span class="predefined-type">URL</span>(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:8080/v2/api-docs</span><span class="delimiter">"</span></span>)).build()
|
||
.toFolder(Paths.get(<span class="string"><span class="delimiter">"</span><span class="content">src/docs/asciidoc/generated</span><span class="delimiter">"</span></span>));
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Spring’s MVC Test framework can also be used to make a request to a Springfox Swagger endpoint during an unit test. A custom ResultHandler <code>Swagger2MarkupResultHandler</code> can be used to write the Swagger JSON response into a directory. The custom ResultHandler is part of <code>springfox-staticdocs</code>. That way you also verify that your Swagger endpoint is working.<br>
|
||
The Swagger JSON response can be converted using the <a href="#_gradle_plugin">Gradle Plugin</a> or <a href="#_maven_plugin">Maven Plugin</a>.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@WebAppConfiguration</span>
|
||
<span class="annotation">@RunWith</span>(SpringJUnit4ClassRunner.class)
|
||
<span class="annotation">@SpringApplicationConfiguration</span>(classes = {Application.class, SwaggerConfig.class})
|
||
<span class="directive">public</span> <span class="type">class</span> <span class="class">Swagger2MarkupTest</span> {
|
||
|
||
<span class="annotation">@Autowired</span>
|
||
<span class="directive">private</span> WebApplicationContext context;
|
||
|
||
<span class="directive">private</span> MockMvc mockMvc;
|
||
|
||
<span class="annotation">@Before</span>
|
||
<span class="directive">public</span> <span class="type">void</span> setUp() {
|
||
<span class="local-variable">this</span>.mockMvc = MockMvcBuilders.webAppContextSetup(<span class="local-variable">this</span>.context).build();
|
||
}
|
||
|
||
<span class="annotation">@Test</span>
|
||
<span class="directive">public</span> <span class="type">void</span> convertSwaggerToAsciiDoc() <span class="directive">throws</span> <span class="exception">Exception</span> {
|
||
<span class="local-variable">this</span>.mockMvc.perform(get(<span class="string"><span class="delimiter">"</span><span class="content">/v2/api-docs</span><span class="delimiter">"</span></span>)
|
||
.accept(MediaType.APPLICATION_JSON))
|
||
.andDo(Swagger2MarkupResultHandler
|
||
.outputDirectory(<span class="string"><span class="delimiter">"</span><span class="content">src/docs/asciidoc/generated</span><span class="delimiter">"</span></span>).build())
|
||
.andExpect(status().isOk());
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_demo"><a class="anchor" href="#_demo"></a><a class="link" href="#_demo">10.1. Demo</a></h3>
|
||
<div class="paragraph">
|
||
<p>The quickest way to get started is to look at the demo project <a href="https://github.com/Swagger2Markup/spring-swagger2markup-demo">spring-swagger2markup-demo</a>. The demo shows how to generate static docs (HTML5 and PDF) by using the Swagger2Markup Gradle Plugin and serve the generated documentation as static content in a Spring Boot App under <a href="http://localhost:9080/docs/index.html" class="bare">http://localhost:9080/docs/index.html</a> and <a href="http://localhost:9080/docs/index.pdf" class="bare">http://localhost:9080/docs/index.pdf</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If you want to start the Spring Boot application, please run:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="CodeRay highlight"><code data-lang="java">gradlew clean build</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre>java -jar build/libs/spring-swagger2markup-demo-{project-version}.jar</pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If you only want to generate the HTML and PDF documentation, please run:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre>gradlew clean asciidoctor</pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_contributing"><a class="anchor" href="#_contributing"></a><a class="link" href="#_contributing">11. Contributing</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="sect2">
|
||
<h3 id="_questions"><a class="anchor" href="#_questions"></a><a class="link" href="#_questions">11.1. Questions</a></h3>
|
||
<div class="paragraph">
|
||
<p>You can ask questions about Swagger2Markup in <a href="https://gitter.im/Swagger2Markup/swagger2markup">Gitter</a>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_bugs"><a class="anchor" href="#_bugs"></a><a class="link" href="#_bugs">11.2. Bugs</a></h3>
|
||
<div class="paragraph">
|
||
<p>If you believe you have found a bug, please take a moment to search the existing issues. If no one else has reported the problem, please open a new issue that describes the problem in detail and, ideally, includes a test that reproduces it.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_enhancements"><a class="anchor" href="#_enhancements"></a><a class="link" href="#_enhancements">11.3. Enhancements</a></h3>
|
||
<div class="paragraph">
|
||
<p>If you’d like an enhancement to be made to Swagger2Markup, pull requests are most welcome. The source code is on GitHub. You may want to search the existing issues and pull requests to see if the enhancement is already being worked on. You may also want to open a new issue to discuss a possible enhancement before work on it begins.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_license"><a class="anchor" href="#_license"></a><a class="link" href="#_license">12. License</a></h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Copyright 2017 Robert Winkler</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at</p>
|
||
</div>
|
||
<div class="literalblock">
|
||
<div class="content">
|
||
<pre>http://www.apache.org/licenses/LICENSE-2.0</pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div id="footer">
|
||
<div id="footer-text">
|
||
Version 1.3.1<br>
|
||
Last updated 2017-10-09 08:56:19 UTC
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |