MOAR DOCS

docs/customization/overview.md

@@ -0,0 +1,53 @@
+# Plugin system overview
+
+### Prior art
+
+Swagger-UI leans heavily on concepts and patterns found in React and Redux.
+
+If you aren't already familiar, here's some suggested reading:
+
+- [React: Quick Start](https://reactjs.org/docs/hello-world.html)
+- [Redux README](http://redux.js.org/)
+
+In the following documentation, we won't take the time to define the fundamentals covered in the resources above.
+
+### The System
+
+The _system_ is the heart of the Swagger-UI application. At runtime, it's a JavaScript object that holds many things:
+
+- React components
+- Bound Redux actions and reducers
+- Bound Reselect state selectors
+- System-wide collection of available components
+- Built-in helpers like `getComponent`, `makeMappedContainer`, and `getStore`
+- User-defined helper functions
+
+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.
+
+### Presets
+
+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:
+
+```javascript
+SwaggerUI({
+  presets: [
+    [FirstPlugin, SecondPlugin],
+    [ThirdPlugin, FourthPlugin]
+  ],
+  plugins: [
+    FifthPlugin,
+    SixthPlugin
+  ]
+})
+```
+
+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:
+
+```javascript
+SwaggerUI({
+  presets: [
+    SwaggerUI.presets.apis,
+    MyAmazingCustomPreset
+  ]
+})
+```

docs/customization/plugin-api.md

@@ -1,15 +1,15 @@
-# Plugin API
+# Plugins
 
-A plugin is an object that contains functions and components capable of modifying and augmenting Swagger-UI's functionality.
+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.
 
 ### Format
 
-A plugin may contain any or all of these keys:
+A plugin return value may contain any of these keys, where `myStateKey` is a name for a piece of state:
 
 ```javascript
-const MyPlugin = {
+{
   statePlugins: {
-    anyStateKey: {
+    myStateKey: {
       actions,
       reducers,
       selectors,
@@ -17,19 +17,66 @@ const MyPlugin = {
       wrapSelectors
     }
   },
-  components: {
+  components: {},
+  wrapComponents: {},
+  fn: {}
+}
+```
 
-  },
-  wrapComponents: {
-    
+### Inputs
+
+Let's assume we have a plugin, `NormalPlugin`, that exposes a `doStuff` action under the `normal` state namespace.
+
+```javascript
+const ExtendingPlugin = function(system) {
+  return {
+    statePlugins: {
+      extending: {
+        actions: {
+          doExtendedThings: function(...args) {
+            // you can do other things in here if you want
+            return system.normalActions.doStuff(...args)
+          }
+        }
+      }
+    }
   }
 }
 ```
 
+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.
+
+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.
+
 ### Interfaces
 
 ##### Actions
 
+```javascript
+const MyActionPlugin = () => {
+  return {
+    statePlugins: {
+      example: {
+        actions: {
+          updateFavoriteColor: (str) => {
+            return {
+              type: "EXAMPLE_SET_FAV_COLOR",
+              payload: str
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+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`.
+
+For more information about the concept of actions in Redux, see the [Redux Actions documentation](http://redux.js.org/docs/basics/Actions.html).
+
 ##### Reducers
 
 ##### Selectors
@@ -41,3 +88,5 @@ const MyPlugin = {
 ##### Wrap-Selectors
 
 ##### Wrap-Components
+
+##### fn