You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
gitbook.page.hasChanged({"page":{"title":"Creating a Custom Layout","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":"Building an Example Plugin","level":"3.2","depth":1,"path":"customization/building-a-plugin.md","ref":"customization/building-a-plugin.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-04T02:18:03.012Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-04T01:43:58.838Z"},"basePath":"..","book":{"language":""}});
350
+
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":""}});
<p>In the following documentation, we won't take the time to define the fundamentals covered in the resources above.</p>
316
+
<h3id="the-system">The System</h3>
317
+
<p>The <em>system</em> is the heart of the Swagger-UI application. At runtime, it's a JavaScript object that holds many things:</p>
318
+
<ul>
319
+
<li>React components</li>
320
+
<li>Bound Redux actions and reducers</li>
321
+
<li>Bound Reselect state selectors</li>
322
+
<li>System-wide collection of available components</li>
323
+
<li>Built-in helpers like <code>getComponent</code>, <code>makeMappedContainer</code>, and <code>getStore</code></li>
324
+
<li>User-defined helper functions</li>
325
+
</ul>
326
+
<p>The system is built up when Swagger-UI is called by iterating through ("compiling") each plugin that Swagger-UI has been given, through the <code>presets</code> and <code>plugins</code> configuration options.</p>
327
+
<h3id="presets">Presets</h3>
328
+
<p>Presets are arrays of plugins, which are provided to Swagger-UI through the <code>presets</code> configuration option. All plugins within presets are compiled before any plugins provided via the <code>plugins</code> configuration option. Consider the following example:</p>
329
+
<pre><codeclass="lang-javascript">SwaggerUI({
330
+
presets: [
331
+
[FirstPlugin, SecondPlugin],
332
+
[ThirdPlugin, FourthPlugin]
333
+
],
334
+
plugins: [
335
+
FifthPlugin,
336
+
SixthPlugin
337
+
]
338
+
})
339
+
</code></pre>
340
+
<p>By default, Swagger-UI includes the internal <code>ApisPreset</code>, which contains a set of plugins that provide baseline functionality for Swagger-UI. If you specify your own <code>presets</code> option, you need to add the ApisPreset manually, like so:</p>
gitbook.page.hasChanged({"page":{"title":"Building an Example Plugin","level":"3.2","depth":1,"next":{"title":"Creating a Custom Layout","level":"3.3","depth":1,"path":"customization/custom-layout.md","ref":"customization/custom-layout.md","articles":[]},"previous":{"title":"Plugin API","level":"3.1","depth":1,"path":"customization/plugin-api.md","ref":"customization/plugin-api.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/building-a-plugin.md","mtime":"2017-10-04T02:17:32.392Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-04T01:43:58.838Z"},"basePath":"..","book":{"language":""}});
391
+
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":""}});
<p>A plugin is an object that contains functions and components capable of modifying and augmenting Swagger-UI's functionality.</p>
307
+
<h1id="plugins">Plugins</h1>
308
+
<p>A plugin is a function that returns an object - more specifically, the object may contain functions and components that augment and modify Swagger-UI's functionality.</p>
309
309
<h3id="format">Format</h3>
310
-
<p>A plugin may contain any or all of these keys:</p>
<p>A plugin return value may contain any of these keys, where <code>myStateKey</code> is a name for a piece of state:</p>
311
+
<pre><codeclass="lang-javascript">{
312
312
statePlugins: {
313
-
anyStateKey: {
313
+
myStateKey: {
314
314
actions,
315
315
reducers,
316
316
selectors,
317
317
wrapActions,
318
318
wrapSelectors
319
319
}
320
320
},
321
-
components: {
322
-
323
-
},
324
-
wrapComponents: {
325
-
321
+
components: {},
322
+
wrapComponents: {},
323
+
fn: {}
324
+
}
325
+
</code></pre>
326
+
<h3id="inputs">Inputs</h3>
327
+
<p>Let's assume we have a plugin, <code>NormalPlugin</code>, that exposes a <code>doStuff</code> action under the <code>normal</code> state namespace.</p>
<p>As you can see, each plugin is passed a reference to the <code>system</code> being built up. As long as <code>NormalPlugin</code> is compiled before <code>ExtendingPlugin</code>, this will work without any issues.</p>
344
+
<p>There is no dependency management built into the plugin system, so if you create a plugin that relies on another, it is your responsibility to make sure that the dependent plugin is loaded <em>after</em> the plugin being depended on.</p>
<p>The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system.</p>
365
+
<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>
366
+
<p>For more information about the concept of actions in Redux, see the <ahref="http://redux.js.org/docs/basics/Actions.html" target="_blank">Redux Actions documentation</a>.</p>
gitbook.page.hasChanged({"page":{"title":"Plugin API","level":"3.1","depth":1,"next":{"title":"Building an Example Plugin","level":"3.2","depth":1,"path":"customization/building-a-plugin.md","ref":"customization/building-a-plugin.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/plugin-api.md","mtime":"2017-10-04T02:39:02.825Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2017-10-04T01:43:58.838Z"},"basePath":"..","book":{"language":""}});
417
+
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":""}});
In the following documentation, we won't take the time to define the fundamentals covered in the resources above.
13
+
14
+
### The System
15
+
16
+
The _system_ is the heart of the Swagger-UI application. At runtime, it's a JavaScript object that holds many things:
17
+
18
+
- React components
19
+
- Bound Redux actions and reducers
20
+
- Bound Reselect state selectors
21
+
- System-wide collection of available components
22
+
- Built-in helpers like `getComponent`, `makeMappedContainer`, and `getStore`
23
+
- User-defined helper functions
24
+
25
+
The system is built up when Swagger-UI is called by iterating through ("compiling") each plugin that Swagger-UI has been given, through the `presets` and `plugins` configuration options.
26
+
27
+
### Presets
28
+
29
+
Presets are arrays of plugins, which are provided to Swagger-UI through the `presets` configuration option. All plugins within presets are compiled before any plugins provided via the `plugins` configuration option. Consider the following example:
30
+
31
+
```javascript
32
+
SwaggerUI({
33
+
presets: [
34
+
[FirstPlugin, SecondPlugin],
35
+
[ThirdPlugin, FourthPlugin]
36
+
],
37
+
plugins: [
38
+
FifthPlugin,
39
+
SixthPlugin
40
+
]
41
+
})
42
+
```
43
+
44
+
By default, Swagger-UI includes the internal `ApisPreset`, which contains a set of plugins that provide baseline functionality for Swagger-UI. If you specify your own `presets` option, you need to add the ApisPreset manually, like so:
A plugin is an object that contains functions and components capable of modifying and augmenting Swagger-UI's functionality.
3
+
A plugin is a function that returns an object - more specifically, the object may contain functions and components that augment and modify Swagger-UI's functionality.
4
4
5
5
### Format
6
6
7
-
A plugin may contain any or all of these keys:
7
+
A plugin return value may contain any of these keys, where `myStateKey` is a name for a piece of state:
8
8
9
9
```javascript
10
-
constMyPlugin={
10
+
{
11
11
statePlugins: {
12
-
anyStateKey: {
12
+
myStateKey: {
13
13
actions,
14
14
reducers,
15
15
selectors,
16
16
wrapActions,
17
17
wrapSelectors
18
18
}
19
19
},
20
-
components: {
20
+
components: {},
21
+
wrapComponents: {},
22
+
fn: {}
23
+
}
24
+
```
21
25
22
-
},
23
-
wrapComponents: {
24
-
26
+
### Inputs
27
+
28
+
Let's assume we have a plugin, `NormalPlugin`, that exposes a `doStuff` action under the `normal` state namespace.
29
+
30
+
```javascript
31
+
constExtendingPlugin=function(system) {
32
+
return {
33
+
statePlugins: {
34
+
extending: {
35
+
actions: {
36
+
doExtendedThings:function(...args) {
37
+
// you can do other things in here if you want
38
+
returnsystem.normalActions.doStuff(...args)
39
+
}
40
+
}
41
+
}
42
+
}
25
43
}
26
44
}
27
45
```
28
46
47
+
As you can see, each plugin is passed a reference to the `system` being built up. As long as `NormalPlugin` is compiled before `ExtendingPlugin`, this will work without any issues.
48
+
49
+
There is no dependency management built into the plugin system, so if you create a plugin that relies on another, it is your responsibility to make sure that the dependent plugin is loaded _after_ the plugin being depended on.
50
+
29
51
### Interfaces
30
52
31
53
##### Actions
32
54
55
+
```javascript
56
+
constMyActionPlugin= () => {
57
+
return {
58
+
statePlugins: {
59
+
example: {
60
+
actions: {
61
+
updateFavoriteColor: (str) => {
62
+
return {
63
+
type:"EXAMPLE_SET_FAV_COLOR",
64
+
payload: str
65
+
}
66
+
}
67
+
}
68
+
}
69
+
}
70
+
}
71
+
}
72
+
```
73
+
74
+
The Action interface enables the creation of new Redux action creators within a piece of state in the Swagger-UI system.
75
+
76
+
This action creator function will be bound to the `example` reducer dispatcher and exposed to container components as `exampleActions.updateFavoriteColor`.
77
+
78
+
For more information about the concept of actions in Redux, see the [Redux Actions documentation](http://redux.js.org/docs/basics/Actions.html).
0 commit comments