Multiple Examples for OpenAPI 3 Parameters, Request Bodies, and Responses

.prettierrc.yaml

@@ -0,0 +1,5 @@
+semi: false
+trailingComma: es5
+endOfLine: lf
+requirePragma: true
+insertPragma: true

src/core/components/example.jsx

@@ -0,0 +1,34 @@
+/**
+ * @prettier
+ */
+
+import React from "react"
+import { stringify } from "core/utils"
+
+export default function Example(props) {
+  const { example, showValue, getComponent } = props
+
+  const Markdown = getComponent("Markdown")
+  const HighlightCode = getComponent("highlightCode")
+
+  if(!example) return null
+
+  return (
+    <div className="example">
+      {example.get("description") ? (
+        <section className="example__section">
+          <div className="example__section-header">Example Description</div>
+          <p>
+            <Markdown source={example.get("description")} />
+          </p>
+        </section>
+      ) : null}
+      {showValue && example.has("value") ? (
+        <section className="example__section">
+          <div className="example__section-header">Example Value</div>
+          <HighlightCode value={stringify(example.get("value"))} />
+        </section>
+      ) : null}
+    </div>
+  )
+}

src/core/components/examples-select-value-retainer.jsx

@@ -0,0 +1,176 @@
+/**
+ * @prettier
+ */
+import React from "react"
+import { Map } from "immutable"
+import PropTypes from "prop-types"
+import ImPropTypes from "react-immutable-proptypes"
+
+import ExamplesSelect from "./examples-select"
+
+// This stateful component lets us avoid writing competing values (user
+// modifications vs example values) into global state, and the mess that comes
+// with that: tracking which of the two values are currently used for
+// Try-It-Out, which example a modified value came from, etc...
+//
+// The solution here is to retain the last user-modified value in
+// ExamplesSelectValueRetainer's component state, so that our global state can stay
+// clean, always simply being the source of truth for what value should be both
+// displayed to the user and used as a value during request execution.
+//
+// This approach/tradeoff was chosen in order to encapsulate the particular
+// logic of Examples within the Examples component tree, and to avoid
+// regressions within our current implementation elsewhere (non-Examples
+// definitions, OpenAPI 2.0, etc). A future refactor to global state might make
+// this component unnecessary.
+//
+// TL;DR: this is not our usual approach, but the choice was made consciously.
+
+export default class ExamplesSelectValueRetainer extends React.PureComponent {
+  static propTypes = {
+    examples: ImPropTypes.map,
+    onSelect: PropTypes.func,
+    updateValue: PropTypes.func, // mechanism to update upstream value
+    getComponent: PropTypes.func.isRequired,
+    currentUserInputValue: PropTypes.any,
+    currentKey: PropTypes.string,
+    // (also proxies props for Examples)
+  }
+
+  static defaultProps = {
+    examples: Map({}),
+    onSelect: (...args) =>
+      console.log(
+        "ExamplesSelectValueRetainer: no `onSelect` function was provided",
+        ...args
+      ),
+    updateValue: (...args) =>
+      console.log(
+        "ExamplesSelectValueRetainer: no `updateValue` function was provided",
+        ...args
+      ),
+  }
+
+  constructor(props) {
+    super(props)
+
+    const valueFromExample = this._getCurrentExampleValue()
+
+    this.state = {
+      // user edited: last value that came from the world around us, and didn't
+      // match the current example's value
+      // internal: last value that came from user selecting an Example
+      lastUserEditedValue: this.props.currentUserInputValue,
+      lastDownstreamValue: valueFromExample,
+      isModifiedValueSelected:
+        valueFromExample !== undefined &&
+        this.props.currentUserInputValue !== valueFromExample,
+    }
+  }
+
+  _isCurrentUserInputSameAsExampleValue = () => {
+    const { currentUserInputValue } = this.props
+
+    const valueFromExample = this._getCurrentExampleValue()
+
+    return valueFromExample === currentUserInputValue
+  }
+
+  _getValueForExample = (exampleKey, props) => {
+    // props are accepted so that this can be used in componentWillReceiveProps,
+    // which has access to `nextProps`
+    const { examples } = props || this.props
+    return (examples || Map({})).getIn([exampleKey, "value"])
+  }
+
+  _getCurrentExampleValue = props => {
+    // props are accepted so that this can be used in componentWillReceiveProps,
+    // which has access to `nextProps`
+    const { currentKey } = props || this.props
+    return this._getValueForExample(currentKey, props || this.props)
+  }
+
+  _onExamplesSelect = (key, { isSyntheticChange } = {}, ...otherArgs) => {
+    const { onSelect, updateValue, currentUserInputValue } = this.props
+    const { lastUserEditedValue } = this.state
+
+    const valueFromExample = this._getValueForExample(key)
+
+    if (key === "__MODIFIED__VALUE__") {
+      updateValue(lastUserEditedValue)
+      return this.setState({
+        isModifiedValueSelected: true,
+      })
+    }
+
+    if (typeof onSelect === "function") {
+      onSelect(key, { isSyntheticChange }, ...otherArgs)
+    }
+
+    this.setState({
+      lastDownstreamValue: valueFromExample,
+      isModifiedValueSelected:
+        isSyntheticChange &&
+        currentUserInputValue &&
+        currentUserInputValue !== valueFromExample,
+    })
+
+    // we never want to send up value updates from synthetic changes
+    if (isSyntheticChange) return
+
+    if (typeof updateValue === "function") {
+      updateValue(valueFromExample)
+    }
+  }
+
+  componentWillReceiveProps(nextProps) {
+    // update `lastUserEditedValue` as new currentUserInput values come in
+
+    const { currentUserInputValue: newValue } = nextProps
+
+    const lastUserEditedValue = this.state.lastUserEditedValue
+    const lastDownstreamValue = this.state.lastDownstreamValue
+
+    const valueFromExample = this._getValueForExample(
+      nextProps.currentKey,
+      nextProps)
+
+    if (
+      newValue !== this.props.currentUserInputValue && // value has changed
+      newValue !== lastUserEditedValue && // value isn't already tracked
+      newValue !== lastDownstreamValue && // value isn't what we've seen on the other side
+      newValue !== valueFromExample // value isn't the example's value
+    ) {
+      this.setState({
+        lastUserEditedValue: nextProps.currentUserInputValue,
+        isModifiedValueSelected: newValue !== valueFromExample,
+      })
+    }
+  }
+
+  render() {
+    const { currentUserInputValue, examples, currentKey } = this.props
+    const {
+      lastDownstreamValue,
+      lastUserEditedValue,
+      isModifiedValueSelected,
+    } = this.state
+
+    return (
+      <div>
+        <ExamplesSelect
+          examples={examples}
+          currentExampleKey={currentKey}
+          onSelect={this._onExamplesSelect}
+          isModifiedValueAvailable={
+            lastUserEditedValue !== undefined &&
+            lastUserEditedValue !== lastDownstreamValue
+          }
+          isValueModified={
+            currentUserInputValue !== undefined && isModifiedValueSelected
+          }
+        />
+      </div>
+    )
+  }
+}

src/core/components/examples-select.jsx

@@ -0,0 +1,115 @@
+/**
+ * @prettier
+ */
+
+import React from "react"
+import Im from "immutable"
+import PropTypes from "prop-types"
+import ImPropTypes from "react-immutable-proptypes"
+
+export default class ExamplesSelect extends React.PureComponent {
+  static propTypes = {
+    examples: ImPropTypes.map.isRequired,
+    onSelect: PropTypes.func,
+    currentExampleKey: PropTypes.string,
+    isModifiedValueAvailable: PropTypes.bool,
+    isValueModified: PropTypes.bool,
+  }
+
+  static defaultProps = {
+    examples: Im.Map({}),
+    onSelect: (...args) =>
+      console.log(
+        // FIXME: remove before merging to master...
+        `DEBUG: ExamplesSelect was not given an onSelect callback`,
+        ...args
+      ),
+    currentExampleKey: null,
+  }
+
+  _onSelect = (key, { isSyntheticChange = false } = {}) => {
+    if (typeof this.props.onSelect === "function") {
+      this.props.onSelect(key, {
+        isSyntheticChange,
+      })
+    }
+  }
+
+  _onDomSelect = e => {
+    if (typeof this.props.onSelect === "function") {
+      const element = e.target.selectedOptions[0]
+      const key = element.getAttribute("value")
+
+      this._onSelect(key, {
+        isSyntheticChange: false,
+      })
+    }
+  }
+
+  getCurrentExample = () => {
+    const { examples, currentKey } = this.props
+
+    const currentExamplePerProps = examples.get(currentKey)
+
+    const firstExamplesKey = examples.keySeq().first()
+    const firstExample = examples.get(firstExamplesKey)
+
+    return currentExamplePerProps || firstExample || Map({})
+  }
+
+
+  componentDidMount() {
+    // this is the not-so-great part of ExamplesSelect... here we're
+    // artificially kicking off an onSelect event in order to set a default
+    // value in state. the consumer has the option to avoid this by checking
+    // `isSyntheticEvent`, but we should really be doing this in a selector.
+    // TODO: clean this up
+    // FIXME: should this only trigger if `currentExamplesKey` is nullish?
+    const { onSelect, examples } = this.props
+
+    if (typeof onSelect === "function") {
+      const firstExample = this.getCurrentExample()
+      const firstExampleKey = examples.keyOf(firstExample)
+
+      this._onSelect(firstExampleKey, {
+        isSyntheticChange: true,
+      })
+    }
+  }
+
+  render() {
+    const {
+      examples,
+      currentExampleKey,
+      isValueModified,
+      isModifiedValueAvailable,
+    } = this.props
+
+    return (
+      <select
+        onChange={this._onDomSelect}
+        value={
+          isModifiedValueAvailable && isValueModified
+            ? "__MODIFIED__VALUE__"
+            : currentExampleKey
+        }
+      >
+        {isModifiedValueAvailable ? (
+          <option value="__MODIFIED__VALUE__">[Modified value]</option>
+        ) : null}
+        {examples
+          .map((example, exampleName) => {
+            return (
+              <option
+                key={exampleName} // for React
+                value={exampleName} // for matching to select's `value`
+              >
+                {example.get("summary") || exampleName}
+              </option>
+            )
+          })
+          .valueSeq()}
+      </select>
+    )
+  }
+}

src/core/components/layout-utils.jsx

@@ -176,12 +176,19 @@ export class Select extends React.Component {
     onChange && onChange(value)
   }
 
+  componentWillReceiveProps(nextProps) {
+    // TODO: this puts us in a weird area btwn un/controlled selection... review
+    if(nextProps.value !== this.props.value) {
+      this.setState({ value: nextProps.value })
+    }
+  }
+
   render(){
     let { allowedValues, multiple, allowEmptyValue } = this.props
     let value = this.state.value.toJS ? this.state.value.toJS() : this.state.value
 
     return (
-      <select className={this.props.className} multiple={ multiple } value={ value } onChange={ this.onChange } >
+      <select className={this.props.className} multiple={ multiple } value={ String(value) } onChange={ this.onChange } >
         { allowEmptyValue ? <option value="">--</option> : null }
         {
           allowedValues.map(function (item, key) {

src/core/components/operation.jsx

@@ -156,6 +156,8 @@ export default class Operation extends PureComponent {
                   specSelectors={ specSelectors }
                   pathMethod={ [path, method] }
                   getConfigs={ getConfigs }
+                  oas3Actions={ oas3Actions }
+                  oas3Selectors={ oas3Selectors }
                 />
               }
 
@@ -214,6 +216,7 @@ export default class Operation extends PureComponent {
                     getConfigs={ getConfigs }
                     specSelectors={ specSelectors }
                     oas3Actions={oas3Actions}
+                    oas3Selectors={oas3Selectors}
                     specActions={ specActions }
                     produces={specSelectors.producesOptionsFor([path, method]) }
                     producesValue={ specSelectors.currentProducesFor([path, method]) }