プラグイン

プラグインはオブジェクトを返す関数です。より具体的には、そのオブジェクトには Swagger UI の機能を拡張および変更する関数とコンポーネントが含まれる場合があります。

注意: セマンティックバージョニング

Swagger UI の内部 API は、当社の公開契約の一部では**ありません**。つまり、メジャーバージョン変更なしに変更される可能性があります。

カスタムプラグインが内部コア API をラップ、拡張、オーバーライド、または使用する場合、アプリケーションで使用する Swagger UI の特定のマイナーバージョンを指定することをお勧めします。これは、パッチバージョン間では**変更されない**ためです。

例えば、NPM 経由で Swagger UI をインストールしている場合、チルダを使用することでこれを行うことができます。

{
  "dependencies": {
    "swagger-ui": "~3.11.0"
  }
}

フォーマット

プラグインの戻り値には、これらのいずれかのキーを含めることができます。stateKey は状態の一部を表す名前です。

{
  statePlugins: {
    [stateKey]: {
      actions,
      reducers,
      selectors,
      wrapActions,
      wrapSelectors
    }
  },
  components: {},
  wrapComponents: {},
  rootInjects: {},
  afterLoad: (system) => {},
  fn: {},
}

システムはプラグインに提供されます

normal 状態の名前空間の下に doStuff アクションを公開するプラグイン NormalPlugin があると仮定しましょう。

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)
          }
        }
      }
    }
  }
}

ご覧のとおり、各プラグインには構築中の system への参照が渡されます。NormalPlugin が ExtendingPlugin の前にコンパイルされる限り、これは問題なく機能します。

プラグインシステムには依存関係管理が組み込まれていないため、他のプラグインに依存するプラグインを作成する場合、依存されるプラグインが**後で**ロードされるようにすることはあなたの責任です。

インターフェース

アクション

const MyActionPlugin = () => {
  return {
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}

アクションが定義されると、システム参照を取得できる場所であればどこでも使用できます。

// elsewhere
system.exampleActions.updateFavoriteColor("blue")

アクションインターフェースは、Swagger UI システムの状態の一部に新しい Redux アクションクリエーターを作成できるようにします。

このアクションクリエーター関数は、コンテナーコンポーネントに exampleActions.updateFavoriteColor として公開されます。このアクションクリエーターが呼び出されると、戻り値（Flux Standard Action であるべきです）は、次のセクションで定義する example リデューサーに渡されます。

Redux のアクションの概念の詳細については、Redux Actions ドキュメントを参照してください。

リデューサー

リデューサーは状態（Immutable.js マップ）とアクションを受け取り、新しい状態を返します。

リデューサーは、この場合 EXAMPLE_SET_FAV_COLOR のように、それが処理するアクションタイプ名の下にシステムに提供されなければなりません。

const MyReducerPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        reducers: {
          "EXAMPLE_SET_FAV_COLOR": (state, action) => {
            // 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
            return state.set("favColor", action.payload)
          }
        }
      }
    }
  }
}

セレクター

セレクターは、名前空間の状態にアクセスして、状態からデータを取得または派生させます。

これらはロジックを一か所に保つ簡単な方法であり、状態データをコンポーネントに直接渡すよりも推奨されます。

const MySelectorPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        selectors: {
          myFavoriteColor: (state) => state.get("favColor")
        }
      }
    }
  }
}

また、Reselect ライブラリを使用してセレクターをメモ化することもできます。Reselect はセレクター呼び出しを自動的にメモ化するため、頻繁に使用されるセレクターにはこれをお勧めします。

import { createSelector } from "reselect"

const MySelectorPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        selectors: {
          // this selector will be memoized after it is run once for a
          // value of `state`
          myFavoriteColor: createSelector((state) => state.get("favColor"))
        }
      }
    }
  }
}

セレクターが定義されると、システム参照を取得できる場所であればどこでも使用できます。

system.exampleSelectors.myFavoriteColor() // gets `favColor` in state for you

コンポーネント

システムに統合するコンポーネントのマップを提供できます。

提供するコンポーネントのキー名に注意してください。これらの名前を使用して、他の場所でコンポーネントを参照する必要があるためです。

class HelloWorldClass extends React.Component {
  render() {
    return <h1>Hello World!</h1>
  }
}

const MyComponentPlugin = function(system) {
  return {
    components: {
      HelloWorldClass: HelloWorldClass
      // components can just be functions, these are called "stateless components"
      HelloWorldStateless: () => <h1>Hello World!</h1>,
    }
  }
}

// elsewhere
const HelloWorldStateless = system.getComponent("HelloWorldStateless")
const HelloWorldClass = system.getComponent("HelloWorldClass")

また、常に null を返すステートレスコンポーネントを作成することで、不要なコンポーネントを「キャンセル」することもできます。

const NeverShowInfoPlugin = function(system) {
  return {
    components: {
      info: () => null
    }
  }
}

システムにコンポーネントが存在しない場合に警告を発生させたくない場合は、config.failSilently を使用できます。

getComponent 引数の順序に注意してください。以下の例では、ブール値 false はコンテナーの存在を指し、3 番目の引数は欠落しているコンポーネントの警告を抑制するために使用される設定オブジェクトです。

const thisVariableWillBeNull = getComponent("not_real", false, { failSilently: true })

ラップアクション

ラップアクションを使用すると、システム内のアクションの動作をオーバーライドできます。

これらは (oriAction, system) => (...args) => result のシグネチャを持つ関数ファクトリです。

ラップアクションの最初の引数は、ラップされるアクションである oriAction です。oriAction を呼び出すのはあなたの責任です。呼び出さない場合、元のアクションは実行されません。

このメカニズムは、組み込みの動作を条件付きでオーバーライドしたり、アクションをリッスンしたりするのに役立ちます。

// FYI: in an actual Swagger UI, `updateSpec` is already defined in the core code
// it's just here for clarity on what's behind the scenes
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: (oriAction, system) => (str) => {
            // here, you can hand the value to some function that exists outside of Swagger UI
            console.log("Here is my API definition", str)
            return oriAction(str) // don't forget! otherwise, Swagger UI won't update
          }
        }
      }
    }
  }
}

ラップセレクター

ラップセレクターを使用すると、システム内のセレクターの動作をオーバーライドできます。

これらは (oriSelector, system) => (state, ...args) => result のシグネチャを持つ関数ファクトリです。

このインターフェースは、コンポーネントに流れるデータを制御するのに役立ちます。コアコードでは、API 定義のバージョンに基づいてセレクターを無効にするためにこれを使用しています。

import { createSelector } from 'reselect'

// FYI: in an actual Swagger UI, the `url` spec selector is already defined
// it's just here for clarity on what's behind the scenes
const MySpecPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        selectors: {
          url: createSelector(
            state => state.get("url")
          )
        }
      }
    }
  }
}

const MyWrapSelectorsPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        wrapSelectors: {
          url: (oriSelector, system) => (state, ...args) => {
            console.log('someone asked for the spec url!!! it is', state.get('url'))
            // you can return other values here...
            // but let's just enable the default behavior
            return oriSelector(state, ...args)
          }
        }
      }
    }
  }
}

ラップコンポーネント

ラップコンポーネントを使用すると、システムに登録されたコンポーネントをオーバーライドできます。

ラップコンポーネントは、(OriginalComponent, system) => props => ReactElement のシグネチャを持つ関数ファクトリです。React コンポーネントクラスを提供したい場合は、(OriginalComponent, system) => ReactClass も機能します。

const MyWrapBuiltinComponentPlugin = function(system) {
  return {
    wrapComponents: {
      info: (Original, system) => (props) => {
        return <div>
          <h3>Hello world! I am above the Info component.</h3>
          <Original {...props} />
        </div>
      }
    }
  }
}

以下に、ラップされるコンポーネントのコードサンプルを含む別の例を示します。

/////  Overriding a component from a plugin

// Here's our normal, unmodified component.
const MyNumberDisplayPlugin = function(system) {
  return {
    components: {
      NumberDisplay: ({ number }) => <span>{number}</span>
    }
  }
}

// Here's a component wrapper defined as a function.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => (props) => {
        if(props.number > 10) {
          return <div>
            <h3>Warning! Big number ahead.</h3>
            <Original {...props} />
          </div>
        } else {
          return <Original {...props} />
        }
      }
    }
  }
}

// Alternatively, here's the same component wrapper defined as a class.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => class WrappedNumberDisplay extends React.component {
        render() {
          if(props.number > 10) {
            return <div>
              <h3>Warning! Big number ahead.</h3>
              <Original {...props} />
            </div>
          } else {
            return <Original {...props} />
          }
        }
      }
    }
  }
}

rootInjects

rootInjects インターフェースを使用すると、システムのトップレベルに値を注入できます。

このインターフェースはオブジェクトを受け取り、実行時にトップレベルのシステムオブジェクトとマージされます。

const MyRootInjectsPlugin = function(system) {
  return {
    rootInjects: {
      myConstant: 123,
      myMethod: (...params) => console.log(...params)
    }
  }
}

afterLoad

afterLoad プラグインメソッドを使用すると、プラグインが登録された後にシステムへの参照を取得できます。

このインターフェースは、バインドされたセレクターまたはアクションによって駆動されるメソッドをアタッチするためにコアコードで使用されます。また、プラグインが既に準備ができていることを必要とするロジック（例えば、リモートエンドポイントから初期データをフェッチして、プラグインが作成するアクションに渡すなど）を実行するためにも使用できます。

this にバインドされたプラグインコンテキストは文書化されていませんが、バインドされたアクションをトップレベルメソッドとしてアタッチする方法の例を以下に示します。

const MyMethodProvidingPlugin = function() {
  return {
    afterLoad(system) {
      // at this point in time, your actions have been bound into the system
      // so you can do things with them
      this.rootInjects = this.rootInjects || {}
      this.rootInjects.myMethod = system.exampleActions.updateFavoriteColor
    },
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}

fn

fn インターフェースを使用すると、ヘルパー関数をシステムに追加して他の場所で使用できます。

import leftPad from "left-pad"

const MyFnPlugin = function(system) {
  return {
    fn: {
      leftPad: leftPad
    }
  }
}