kyy/swagger-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tremendous, beautiful plugin docs

Browse Source
This commit is contained in:
Kyle Shockey
2017-10-04 20:52:28 -07:00
parent d133f5c2df
commit 24463652a5
14 changed files with 628 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/SUMMARY.md
View File

@@ -8,7 +8,7 @@
### Customization ### Customization
- [Overview](customization/overview.md) - [Overview](customization/overview.md)
- [Creating a Custom Layout](customization/custom-layout.md) - [Creating a custom layout](customization/custom-layout.md)
- [Plugin API](customization/plugin-api.md) - [Plugin API](customization/plugin-api.md)
### Development ### Development

92
docs/_book/customization/custom-layout.html
View File

@@ -4,7 +4,7 @@
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"> <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Creating a Custom Layout · Swagger-UI</title> <title>Creating a custom layout · Swagger-UI</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content=""> <meta name="description" content="">
<meta name="generator" content="GitBook 3.2.3"> <meta name="generator" content="GitBook 3.2.3">
@@ -192,7 +192,7 @@
<a href="custom-layout.html"> <a href="custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>
@@ -289,7 +289,7 @@
<!-- Title --> <!-- Title -->
<h1> <h1>
<i class="fa fa-circle-o-notch fa-spin"></i> <i class="fa fa-circle-o-notch fa-spin"></i>
<a href=".." >Creating a Custom Layout</a> <a href=".." >Creating a custom layout</a>
</h1> </h1>
</div> </div>
@@ -304,7 +304,89 @@
<section class="normal markdown-section"> <section class="normal markdown-section">
<h1 id="creating-a-custom-layout">Creating a custom layout</h1>
<p><strong>Layouts</strong> are a special type of component that Swagger-UI uses as the root component for the entire application. You can define custom layouts in order to have high-level control over what ends up on the page.</p>
<p>By default, Swagger-UI uses <code>BaseLayout</code>, which is built into the application. You can specify a different layout to be used by passing the layout&apos;s name as the <code>layout</code> parameter to Swagger-UI. Be sure to provide your custom layout as a component to Swagger-UI.</p>
<p><br></p>
<p>For example, if you wanted to create a custom layout that only displayed operations, you could define an <code>OperationsLayout</code>:</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> React <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;react&quot;</span>
<span class="hljs-comment">// Create the layout component</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">OperationsLayout</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">React</span>.<span class="hljs-title">Component</span> </span>{
render() {
<span class="hljs-keyword">const</span> {
getComponent
} = <span class="hljs-keyword">this</span>.props
<span class="hljs-keyword">const</span> Operations = getComponent(<span class="hljs-string">&quot;Operations&quot;</span>, <span class="hljs-literal">true</span>)
<span class="hljs-keyword">return</span> {
<span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">Operations</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
}
}
}
// Create the plugin that provides our layout component
const OperationsLayoutPlugin = function() {
return {
components: {
OperationsLayout: OperationsLayout
}
}
}
// Provide the plugin to Swagger-UI, and select OperationsLayout
// as the layout for Swagger-UI
SwaggerUI({
url: &quot;http://petstore.swagger.io/v2/swagger.json&quot;,
plugins: [ OperationsLayoutPlugin ],
layout: &quot;OperationsLayout&quot;
})
</span></code></pre>
<h3 id="augmenting-the-default-layout">Augmenting the default layout</h3>
<p>If you&apos;d like to build around the <code>BaseLayout</code> instead of replacing it, you can pull the <code>BaseLayout</code> into your custom layout and use it:</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> React <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;react&quot;</span>
<span class="hljs-comment">// Create the layout component</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">AugmentingLayout</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">React</span>.<span class="hljs-title">Component</span> </span>{
render() {
<span class="hljs-keyword">const</span> {
getComponent
} = <span class="hljs-keyword">this</span>.props
<span class="hljs-keyword">const</span> BaseLayout = getComponent(<span class="hljs-string">&quot;BaseLayout&quot;</span>, <span class="hljs-literal">true</span>)
<span class="hljs-keyword">return</span> {
<span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">className</span>=<span class="hljs-string">&quot;myCustomHeader&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">h1</span>&gt;</span>I have a custom header above Swagger-UI!<span class="hljs-tag">&lt;/<span class="hljs-name">h1</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">BaseLayout</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
}
}
}
// Create the plugin that provides our layout component
const AugmentingLayoutPlugin = function() {
return {
components: {
AugmentingLayout: AugmentingLayout
}
}
}
// Provide the plugin to Swagger-UI, and select AugmentingLayout
// as the layout for Swagger-UI
SwaggerUI({
url: &quot;http://petstore.swagger.io/v2/swagger.json&quot;,
plugins: [ AugmentingLayoutPlugin ],
layout: &quot;AugmentingLayout&quot;
})
</span></code></pre>
</section> </section>
@@ -347,7 +429,7 @@
<script> <script>
var gitbook = gitbook || []; var gitbook = gitbook || [];
gitbook.push(function() { gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Creating a Custom Layout","level":"3.2","depth":1,"next":{"title":"Plugin API","level":"3.3","depth":1,"path":"customization/plugin-api.md","ref":"customization/plugin-api.md","articles":[]},"previous":{"title":"Overview","level":"3.1","depth":1,"path":"customization/overview.md","ref":"customization/overview.md","articles":[]},"dir":"neutral"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/custom-layout.md","mtime":"2017-10-05T23:29:46.881Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}}); gitbook.page.hasChanged({"page":{"title":"Creating a custom layout","level":"3.2","depth":1,"next":{"title":"Plugin API","level":"3.3","depth":1,"path":"customization/plugin-api.md","ref":"customization/plugin-api.md","articles":[]},"previous":{"title":"Overview","level":"3.1","depth":1,"path":"customization/overview.md","ref":"customization/overview.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/custom-layout.md","mtime":"2017-10-06T21:59:49.674Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}});
}); });
</script> </script>
</div> </div>

20
docs/_book/customization/overview.html
View File

@@ -192,7 +192,7 @@
<a href="custom-layout.html"> <a href="custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>
@@ -309,10 +309,14 @@
<p>Swagger-UI leans heavily on concepts and patterns found in React and Redux.</p> <p>Swagger-UI leans heavily on concepts and patterns found in React and Redux.</p>
<p>If you aren&apos;t already familiar, here&apos;s some suggested reading:</p> <p>If you aren&apos;t already familiar, here&apos;s some suggested reading:</p>
<ul> <ul>
<li><a href="https://reactjs.org/docs/hello-world.html" target="_blank">React: Quick Start</a></li> <li><a href="https://reactjs.org/docs/hello-world.html" target="_blank">React: Quick Start (reactjs.org)</a></li>
<li><a href="http://redux.js.org/" target="_blank">Redux README</a></li> <li><a href="http://redux.js.org/" target="_blank">Redux README (redux.js.org)</a></li>
</ul> </ul>
<p>In the following documentation, we won&apos;t take the time to define the fundamentals covered in the resources above.</p> <p>In the following documentation, we won&apos;t take the time to define the fundamentals covered in the resources above.</p>
<blockquote>
<p><strong>Note</strong>: Some of the examples in this section contain JSX, which is a syntax extension to JavaScript that is useful for writing React components.</p>
<p>If you don&apos;t want to set up a build pipeline capable of translating JSX to JavaScript, take a look at <a href="https://reactjs.org/docs/react-without-jsx.html" target="_blank">React without JSX (reactjs.org)</a>.</p>
</blockquote>
<h3 id="the-system">The System</h3> <h3 id="the-system">The System</h3>
<p>The <em>system</em> is the heart of the Swagger-UI application. At runtime, it&apos;s a JavaScript object that holds many things:</p> <p>The <em>system</em> is the heart of the Swagger-UI application. At runtime, it&apos;s a JavaScript object that holds many things:</p>
<ul> <ul>
@@ -345,6 +349,12 @@
] ]
}) })
</code></pre> </code></pre>
<h3 id="getcomponent">getComponent</h3>
<p><code>getComponent</code> is a helper function injected into every container component, which is used to get references to components provided by the plugin system.</p>
<p>All components should be loaded through <code>getComponent</code>, since it allows other plugins to modify the component. It is preferred over a conventional <code>import</code> statement.</p>
<p>Container components in Swagger-UI can be loaded by passing <code>true</code> as the second argument to <code>getComponent</code>, like so:</p>
<pre><code>getComponent(&quot;ContainerComponentName&quot;, true)
</code></pre><p>This will map the current system as props to the component.</p>
</section> </section>
@@ -377,7 +387,7 @@
</a> </a>
<a href="custom-layout.html" class="navigation navigation-next " aria-label="Next page: Creating a Custom Layout"> <a href="custom-layout.html" class="navigation navigation-next " aria-label="Next page: Creating a custom layout">
<i class="fa fa-angle-right"></i> <i class="fa fa-angle-right"></i>
</a> </a>
@@ -388,7 +398,7 @@
<script> <script>
var gitbook = gitbook || []; var gitbook = gitbook || [];
gitbook.push(function() { gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Overview","level":"3.1","depth":1,"next":{"title":"Creating a Custom Layout","level":"3.2","depth":1,"path":"customization/custom-layout.md","ref":"customization/custom-layout.md","articles":[]},"previous":{"title":"Version detection","level":"2.3","depth":1,"path":"usage/version-detection.md","ref":"usage/version-detection.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/overview.md","mtime":"2017-10-06T07:15:00.038Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}}); gitbook.page.hasChanged({"page":{"title":"Overview","level":"3.1","depth":1,"next":{"title":"Creating a custom layout","level":"3.2","depth":1,"path":"customization/custom-layout.md","ref":"customization/custom-layout.md","articles":[]},"previous":{"title":"Version detection","level":"2.3","depth":1,"path":"usage/version-detection.md","ref":"usage/version-detection.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/overview.md","mtime":"2017-10-06T22:21:23.876Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}});
}); });
</script> </script>
</div> </div>

175
docs/_book/customization/plugin-api.html
View File

@@ -192,7 +192,7 @@
<a href="custom-layout.html"> <a href="custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>
@@ -349,7 +349,7 @@
statePlugins: { statePlugins: {
example: { example: {
actions: { actions: {
updateFavoriteColor: (str) =&gt; { updateFavoriteColor: (obj) =&gt; {
<span class="hljs-keyword">return</span> { <span class="hljs-keyword">return</span> {
type: <span class="hljs-string">&quot;EXAMPLE_SET_FAV_COLOR&quot;</span>, type: <span class="hljs-string">&quot;EXAMPLE_SET_FAV_COLOR&quot;</span>,
payload: str payload: str
@@ -361,16 +361,183 @@
} }
} }
</code></pre> </code></pre>
<pre><code class="lang-js"><span class="hljs-comment">// elsewhere</span>
exampleActions.updateFavoriteColor({
name: <span class="hljs-string">&quot;blue&quot;</span>,
hex: <span class="hljs-string">&quot;#0000ff&quot;</span>
})
</code></pre>
<p>The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system.</p> <p>The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system.</p>
<p>This action creator function will be bound to the <code>example</code> reducer dispatcher and exposed to container components as <code>exampleActions.updateFavoriteColor</code>.</p> <p>This action creator function will be bound to the <code>example</code> reducer dispatcher and exposed to container components as <code>exampleActions.updateFavoriteColor</code>.</p>
<p>For more information about the concept of actions in Redux, see the <a href="http://redux.js.org/docs/basics/Actions.html" target="_blank">Redux Actions documentation</a>.</p> <p>For more information about the concept of actions in Redux, see the <a href="http://redux.js.org/docs/basics/Actions.html" target="_blank">Redux Actions documentation</a>.</p>
<h5 id="reducers">Reducers</h5> <h5 id="reducers">Reducers</h5>
<p>Reducers take a state (which is an Immutable map) and an action, and return a new state.</p>
<p>Reducers must be provided to the system under the name of the action type that they handle, in this case, <code>MYPLUGIN_UPDATE_SOMETHING</code>.</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> MyReducerPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
example: {
reducers: {
<span class="hljs-string">&quot;EXAMPLE_SET_FAV_COLOR&quot;</span>: (state, action) =&gt; {
<span class="hljs-comment">//</span>
<span class="hljs-keyword">return</span> state.set(<span class="hljs-string">&quot;favColor&quot;</span>, fromJS(action.payload))
<span class="hljs-comment">// we&apos;re updating the Immutable state object...</span>
<span class="hljs-comment">// we need to convert vanilla objects into an immutable type (fromJS)</span>
<span class="hljs-comment">// See immutable docs about how to modify the state</span>
<span class="hljs-comment">// PS: you&apos;re only working with the state under the namespace, in this case &quot;example&quot;.</span>
<span class="hljs-comment">// So you can do what you want, without worrying about /other/ namespaces</span>
}
}
}
}
}
}
</code></pre>
<h5 id="selectors">Selectors</h5> <h5 id="selectors">Selectors</h5>
<p>Selectors take any number of functions as arguments, and passes all results to the last function.</p>
<p>They&apos;re an easy way to keep logic for getting data out of state in one place, and is preferred over passing state data directly into components.</p>
<p>See <a href="https://github.com/reactjs/reselect#createselectorinputselectors--inputselectors-resultfunc" target="_blank">Reselect: <code>createSelector</code></a> for more information.</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> MySelectorPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
myPlugin: {
selectors: {
something: createSelector(
state =&gt; state.get(<span class="hljs-string">&quot;something&quot;</span>) <span class="hljs-comment">// return the whatever &quot;something&quot; points to</span>
)
}
}
}
}
}
</code></pre>
<h5 id="components">Components</h5> <h5 id="components">Components</h5>
<p>You can provide a map of components to be integrated into the system.</p>
<p>Be mindful of the key names for the components you provide, as you&apos;ll need to use those names to refer to the components elsewhere.</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> MyComponentPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
components: {
<span class="hljs-comment">// components can just be functions</span>
HelloWorld: () =&gt; <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">h1</span>&gt;</span>Hello World!<span class="hljs-tag">&lt;/<span class="hljs-name">h1</span>&gt;</span></span>
}
}
}
</code></pre>
<pre><code class="lang-js"><span class="hljs-comment">// elsewhere</span>
<span class="hljs-keyword">const</span> HelloWorld = getComponent(<span class="hljs-string">&quot;HelloWorld&quot;</span>)
</code></pre>
<h5 id="wrap-actions">Wrap-Actions</h5> <h5 id="wrap-actions">Wrap-Actions</h5>
<p>Wrap Actions allow you to override the behavior of an action in the system.</p>
<p>This interface is very useful for building custom behavior on top of builtin actions.</p>
<p>A Wrap Action&apos;s first argument is <code>oriAction</code>, which is the action being wrapped. It is your responsibility to call the <code>oriAction</code> - if you don&apos;t, the original action will not fire!</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> MySpecPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
spec: {
actions: {
updateSpec: (str) =&gt; {
<span class="hljs-keyword">return</span> {
type: <span class="hljs-string">&quot;SPEC_UPDATE_SPEC&quot;</span>,
payload: str
}
}
}
}
}
}
}
<span class="hljs-comment">// this plugin allows you to watch changes to the spec that is in memory</span>
<span class="hljs-keyword">const</span> MyWrapActionPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
spec: {
wrapActions: {
updateSpec: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">oriAction, str</span>) </span>{
doSomethingWithSpecValue(str)
<span class="hljs-keyword">return</span> oriAction(str) <span class="hljs-comment">// don&apos;t forget!</span>
}
}
}
}
}
}
</code></pre>
<h5 id="wrap-selectors">Wrap-Selectors</h5> <h5 id="wrap-selectors">Wrap-Selectors</h5>
<p>Wrap Selectors allow you to override the behavior of a selector in the system.</p>
<p>They are function factories with the signature <code>(oriSelector, system) =&gt; (...args) =&gt; result</code>.</p>
<p>This interface is useful for controlling what data flows into components. We use this in the core code to disable selectors based on the API definition&apos;s version.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> { createSelector } <span class="hljs-keyword">from</span> <span class="hljs-string">&apos;reselect&apos;</span>
<span class="hljs-keyword">const</span> MySpecPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
spec: {
selectors: {
someData: createSelector(
state =&gt; state.get(<span class="hljs-string">&quot;something&quot;</span>)
)
}
}
}
}
}
<span class="hljs-keyword">const</span> MyWrapSelectorsPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
statePlugins: {
spec: {
wrapSelectors: {
someData: (oriSelector, system) =&gt; (...args) =&gt; {
<span class="hljs-comment">// you can do other things here...</span>
<span class="hljs-comment">// but let&apos;s just enable the default behavior</span>
<span class="hljs-keyword">return</span> oriSelector(...args)
}
}
}
}
}
}
</code></pre>
<h5 id="wrap-components">Wrap-Components</h5> <h5 id="wrap-components">Wrap-Components</h5>
<p>Wrap Components allow you to override a component registered within the system.</p>
<p>Wrap Components are function factories with the signature <code>(OriginalComponent, system) =&gt; props =&gt; ReactElement</code>.</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> MyNumberDisplayPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
components: {
NumberDisplay: ({ number }) =&gt; <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">span</span>&gt;</span>{number}<span class="hljs-tag">&lt;/<span class="hljs-name">span</span>&gt;</span></span>
}
}
}
<span class="hljs-keyword">const</span> MyWrapComponentPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
wrapComponents: {
NumberDisplay: (Original, system) =&gt; (props) =&gt; {
<span class="hljs-keyword">if</span>(props.number &gt; <span class="hljs-number">10</span>) {
<span class="hljs-keyword">return</span> <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">div</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">h3</span>&gt;</span>Warning! Big number ahead.<span class="hljs-tag">&lt;/<span class="hljs-name">h3</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span></span>
} <span class="hljs-keyword">else</span> {
<span class="hljs-keyword">return</span> <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">Original</span> {<span class="hljs-attr">...props</span>} /&gt;</span>
}
}
}
}
}
</span></code></pre>
<h5 id="fn">fn</h5> <h5 id="fn">fn</h5>
<p>The fn interface allows you to add helper functions to the system for use elsewhere.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> leftPad <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;left-pad&quot;</span>
<span class="hljs-keyword">const</span> MyFnPlugin = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">system</span>) </span>{
<span class="hljs-keyword">return</span> {
fn: {
leftPad: leftPad
}
}
}
</code></pre>
</section> </section>
@@ -398,7 +565,7 @@
<a href="custom-layout.html" class="navigation navigation-prev " aria-label="Previous page: Creating a Custom Layout"> <a href="custom-layout.html" class="navigation navigation-prev " aria-label="Previous page: Creating a custom layout">
<i class="fa fa-angle-left"></i> <i class="fa fa-angle-left"></i>
</a> </a>
@@ -414,7 +581,7 @@
<script> <script>
var gitbook = gitbook || []; var gitbook = gitbook || [];
gitbook.push(function() { gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Plugin API","level":"3.3","depth":1,"next":{"title":"Architecture overview","level":"4.1","depth":1,"path":"development/architecture.md","ref":"development/architecture.md","articles":[]},"previous":{"title":"Creating a Custom Layout","level":"3.2","depth":1,"path":"customization/custom-layout.md","ref":"customization/custom-layout.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/plugin-api.md","mtime":"2017-10-06T07:38:26.729Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}}); gitbook.page.hasChanged({"page":{"title":"Plugin API","level":"3.3","depth":1,"next":{"title":"Architecture overview","level":"4.1","depth":1,"path":"development/architecture.md","ref":"development/architecture.md","articles":[]},"previous":{"title":"Creating a custom layout","level":"3.2","depth":1,"path":"customization/custom-layout.md","ref":"customization/custom-layout.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"customization/plugin-api.md","mtime":"2017-10-06T23:51:05.316Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}});
}); });
</script> </script>
</div> </div>

2
docs/_book/index.html
View File

@@ -190,7 +190,7 @@
<a href="customization/custom-layout.html"> <a href="customization/custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>

2
docs/_book/search_index.json
View File

File diff suppressed because one or more lines are too long

2
docs/_book/usage/configuration.html
View File

@@ -192,7 +192,7 @@
<a href="../customization/custom-layout.html"> <a href="../customization/custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>

2
docs/_book/usage/deep-linking.html
View File

@@ -192,7 +192,7 @@
<a href="../customization/custom-layout.html"> <a href="../customization/custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>

19
docs/_book/usage/installation.html
View File

@@ -192,7 +192,7 @@
<a href="../customization/custom-layout.html"> <a href="../customization/custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>
@@ -330,9 +330,18 @@ app.use(express.static(pathToSwaggerUi))
app.listen(<span class="hljs-number">3000</span>) app.listen(<span class="hljs-number">3000</span>)
</code></pre> </code></pre>
<h3 id="docker-hub">Docker Hub</h3> <h3 id="docker-hub">Docker Hub</h3>
<h3 id="packagist">Packagist</h3> <p>You can pull a pre-built docker image of the swagger-ui directly from Dockerhub:</p>
<h3 id="unpkg">unpkg</h3> <pre><code>docker pull swaggerapi/swagger-ui
<h1 id="integration">Integration</h1> docker run -p 80:8080 swaggerapi/swagger-ui
</code></pre><p>Will start nginx with swagger-ui on port 80.</p>
<p>Or you can provide your own swagger.json on your host</p>
<pre><code>docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
</code></pre><h3 id="unpkg">unpkg</h3>
<p>You can embed Swagger-UI&apos;s code directly in your HTML by using unkpg&apos;s interface:</p>
<pre><code class="lang-html"><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js&quot;</span>&gt;</span><span class="handlebars"><span class="xml">
<span class="hljs-comment">&lt;!-- `SwaggerUIBundle` is now available on the page --&gt;</span>
</span></span></code></pre>
<p>See <a href="https://unpkg.com/" target="_blank">unpkg&apos;s main page</a> for more information on how to use unpkg.</p>
</section> </section>
@@ -376,7 +385,7 @@ app.listen(<span class="hljs-number">3000</span>)
<script> <script>
var gitbook = gitbook || []; var gitbook = gitbook || [];
gitbook.push(function() { gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Installation","level":"2.1","depth":1,"next":{"title":"Configuration","level":"2.2","depth":1,"path":"usage/configuration.md","ref":"usage/configuration.md","articles":[{"title":"deepLinking","level":"2.2.1","depth":2,"path":"usage/deep-linking.md","ref":"usage/deep-linking.md","articles":[]}]},"previous":{"title":"Intro","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"usage/installation.md","mtime":"2017-10-05T23:29:46.882Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}}); gitbook.page.hasChanged({"page":{"title":"Installation","level":"2.1","depth":1,"next":{"title":"Configuration","level":"2.2","depth":1,"path":"usage/configuration.md","ref":"usage/configuration.md","articles":[{"title":"deepLinking","level":"2.2.1","depth":2,"path":"usage/deep-linking.md","ref":"usage/deep-linking.md","articles":[]}]},"previous":{"title":"Intro","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[]},"dir":"ltr"},"config":{"plugins":["livereload"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"livereload":{},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Swagger-UI","gitbook":"*"},"file":{"path":"usage/installation.md","mtime":"2017-10-06T23:34:59.762Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-06T04:20:18.617Z"},"basePath":"..","book":{"language":""}});
}); });
</script> </script>
</div> </div>

2
docs/_book/usage/version-detection.html
View File

@@ -192,7 +192,7 @@
<a href="../customization/custom-layout.html"> <a href="../customization/custom-layout.html">
Creating a Custom Layout Creating a custom layout
</a> </a>

92
docs/customization/custom-layout.md
View File

@@ -0,0 +1,92 @@
# Creating a custom layout
**Layouts** are a special type of component that Swagger-UI uses as the root component for the entire application. You can define custom layouts in order to have high-level control over what ends up on the page.
By default, Swagger-UI uses `BaseLayout`, which is built into the application. You can specify a different layout to be used by passing the layout's name as the `layout` parameter to Swagger-UI. Be sure to provide your custom layout as a component to Swagger-UI.
<br>
For example, if you wanted to create a custom layout that only displayed operations, you could define an `OperationsLayout`:
```js
import React from "react"
// Create the layout component
class OperationsLayout extends React.Component {
render() {
const {
getComponent
} = this.props
const Operations = getComponent("Operations", true)
return {
<div>
<Operations />
</div>
}
}
}
// Create the plugin that provides our layout component
const OperationsLayoutPlugin = function() {
return {
components: {
OperationsLayout: OperationsLayout
}
}
}
// Provide the plugin to Swagger-UI, and select OperationsLayout
// as the layout for Swagger-UI
SwaggerUI({
url: "http://petstore.swagger.io/v2/swagger.json",
plugins: [ OperationsLayoutPlugin ],
layout: "OperationsLayout"
})
```
### Augmenting the default layout
If you'd like to build around the `BaseLayout` instead of replacing it, you can pull the `BaseLayout` into your custom layout and use it:
```js
import React from "react"
// Create the layout component
class AugmentingLayout extends React.Component {
render() {
const {
getComponent
} = this.props
const BaseLayout = getComponent("BaseLayout", true)
return {
<div>
<div className="myCustomHeader">
<h1>I have a custom header above Swagger-UI!</h1>
</div>
<BaseLayout />
</div>
}
}
}
// Create the plugin that provides our layout component
const AugmentingLayoutPlugin = function() {
return {
components: {
AugmentingLayout: AugmentingLayout
}
}
}
// Provide the plugin to Swagger-UI, and select AugmentingLayout
// as the layout for Swagger-UI
SwaggerUI({
url: "http://petstore.swagger.io/v2/swagger.json",
plugins: [ AugmentingLayoutPlugin ],
layout: "AugmentingLayout"
})
```

22
docs/customization/overview.md
View File

@@ -6,11 +6,15 @@ Swagger-UI leans heavily on concepts and patterns found in React and Redux.
If you aren't already familiar, here's some suggested reading: If you aren't already familiar, here's some suggested reading:
- [React: Quick Start](https://reactjs.org/docs/hello-world.html) - [React: Quick Start (reactjs.org)](https://reactjs.org/docs/hello-world.html)
- [Redux README](http://redux.js.org/) - [Redux README (redux.js.org)](http://redux.js.org/)
In the following documentation, we won't take the time to define the fundamentals covered in the resources above. In the following documentation, we won't take the time to define the fundamentals covered in the resources above.
> **Note**: Some of the examples in this section contain JSX, which is a syntax extension to JavaScript that is useful for writing React components.
>
> If you don't want to set up a build pipeline capable of translating JSX to JavaScript, take a look at [React without JSX (reactjs.org)](https://reactjs.org/docs/react-without-jsx.html).
### The System ### The System
The _system_ is the heart of the Swagger-UI application. At runtime, it's a JavaScript object that holds many things: The _system_ is the heart of the Swagger-UI application. At runtime, it's a JavaScript object that holds many things:
@@ -51,3 +55,17 @@ SwaggerUI({
] ]
}) })
``` ```
### getComponent
`getComponent` is a helper function injected into every container component, which is used to get references to components provided by the plugin system.
All components should be loaded through `getComponent`, since it allows other plugins to modify the component. It is preferred over a conventional `import` statement.
Container components in Swagger-UI can be loaded by passing `true` as the second argument to `getComponent`, like so:
```
getComponent("ContainerComponentName", true)
```
This will map the current system as props to the component.

202
docs/customization/plugin-api.md
View File

@@ -58,7 +58,7 @@ const MyActionPlugin = () => {
statePlugins: { statePlugins: {
example: { example: {
actions: { actions: {
updateFavoriteColor: (str) => { updateFavoriteColor: (obj) => {
return { return {
type: "EXAMPLE_SET_FAV_COLOR", type: "EXAMPLE_SET_FAV_COLOR",
payload: str payload: str
@@ -71,6 +71,14 @@ const MyActionPlugin = () => {
} }
``` ```
```js
// elsewhere
exampleActions.updateFavoriteColor({
name: "blue",
hex: "#0000ff"
})
```
The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system. The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system.
This action creator function will be bound to the `example` reducer dispatcher and exposed to container components as `exampleActions.updateFavoriteColor`. This action creator function will be bound to the `example` reducer dispatcher and exposed to container components as `exampleActions.updateFavoriteColor`.
@@ -79,14 +87,206 @@ For more information about the concept of actions in Redux, see the [Redux Actio
##### Reducers ##### Reducers
Reducers take a state (which is an Immutable map) and an action, and return a new state.
Reducers must be provided to the system under the name of the action type that they handle, in this case, `MYPLUGIN_UPDATE_SOMETHING`.
```js
const MyReducerPlugin = function(system) {
return {
statePlugins: {
example: {
reducers: {
"EXAMPLE_SET_FAV_COLOR": (state, action) => {
//
return state.set("favColor", fromJS(action.payload))
// we're updating the Immutable state object...
// we need to convert vanilla objects into an immutable type (fromJS)
// See immutable docs about how to modify the state
// PS: you're only working with the state under the namespace, in this case "example".
// So you can do what you want, without worrying about /other/ namespaces
}
}
}
}
}
}
```
##### Selectors ##### Selectors
Selectors take any number of functions as arguments, and passes all results to the last function.
They're an easy way to keep logic for getting data out of state in one place, and is preferred over passing state data directly into components.
See [Reselect: `createSelector`](https://github.com/reactjs/reselect#createselectorinputselectors--inputselectors-resultfunc) for more information.
```js
const MySelectorPlugin = function(system) {
return {
statePlugins: {
myPlugin: {
selectors: {
something: createSelector(
state => state.get("something") // return the whatever "something" points to
)
}
}
}
}
}
```
##### Components ##### Components
You can provide a map of components to be integrated into the system.
Be mindful of the key names for the components you provide, as you'll need to use those names to refer to the components elsewhere.
```js
const MyComponentPlugin = function(system) {
return {
components: {
// components can just be functions
HelloWorld: () => <h1>Hello World!</h1>
}
}
}
```
```js
// elsewhere
const HelloWorld = getComponent("HelloWorld")
```
##### Wrap-Actions ##### Wrap-Actions
Wrap Actions allow you to override the behavior of an action in the system.
This interface is very useful for building custom behavior on top of builtin actions.
A Wrap Action's first argument is `oriAction`, which is the action being wrapped. It is your responsibility to call the `oriAction` - if you don't, the original action will not fire!
```js
const MySpecPlugin = function(system) {
return {
statePlugins: {
spec: {
actions: {
updateSpec: (str) => {
return {
type: "SPEC_UPDATE_SPEC",
payload: str
}
}
}
}
}
}
}
// this plugin allows you to watch changes to the spec that is in memory
const MyWrapActionPlugin = function(system) {
return {
statePlugins: {
spec: {
wrapActions: {
updateSpec: function(oriAction, str) {
doSomethingWithSpecValue(str)
return oriAction(str) // don't forget!
}
}
}
}
}
}
```
##### Wrap-Selectors ##### Wrap-Selectors
Wrap Selectors allow you to override the behavior of a selector in the system.
They are function factories with the signature `(oriSelector, system) => (...args) => result`.
This interface is useful for controlling what data flows into components. We use this in the core code to disable selectors based on the API definition's version.
```js
import { createSelector } from 'reselect'
const MySpecPlugin = function(system) {
return {
statePlugins: {
spec: {
selectors: {
someData: createSelector(
state => state.get("something")
)
}
}
}
}
}
const MyWrapSelectorsPlugin = function(system) {
return {
statePlugins: {
spec: {
wrapSelectors: {
someData: (oriSelector, system) => (...args) => {
// you can do other things here...
// but let's just enable the default behavior
return oriSelector(...args)
}
}
}
}
}
}
```
##### Wrap-Components ##### Wrap-Components
Wrap Components allow you to override a component registered within the system.
Wrap Components are function factories with the signature `(OriginalComponent, system) => props => ReactElement`.
```js
const MyNumberDisplayPlugin = function(system) {
return {
components: {
NumberDisplay: ({ number }) => <span>{number}</span>
}
}
}
const MyWrapComponentPlugin = function(system) {
return {
wrapComponents: {
NumberDisplay: (Original, system) => (props) => {
if(props.number > 10) {
return <div>
<h3>Warning! Big number ahead.</h3>
</div>
} else {
return <Original {...props} />
}
}
}
}
}
```
##### fn ##### fn
The fn interface allows you to add helper functions to the system for use elsewhere.
```js
import leftPad from "left-pad"
const MyFnPlugin = function(system) {
return {
fn: {
leftPad: leftPad
}
}
}
```

24
docs/usage/installation.md
View File

@@ -39,8 +39,28 @@ app.listen(3000)
### Docker Hub ### Docker Hub
### Packagist You can pull a pre-built docker image of the swagger-ui directly from Dockerhub:
```
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui
```
Will start nginx with swagger-ui on port 80.
Or you can provide your own swagger.json on your host
```
docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
```
### unpkg ### unpkg
# Integration You can embed Swagger-UI's code directly in your HTML by using unkpg's interface:
```html
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js">
<!-- `SwaggerUIBundle` is now available on the page -->
```
See [unpkg's main page](https://unpkg.com/) for more information on how to use unpkg.