rest-api-page.html

<link rel="import" href="../polymer/polymer.html">
<link href='https://fonts.googleapis.com/css?family=Roboto:400,400italic' rel='stylesheet' type='text/css'>

<link rel="import" href="../paper-drawer-panel/paper-drawer-panel.html">
<link rel="import" href="../paper-header-panel/paper-header-panel.html">
<link rel="import" href="../paper-toolbar/paper-toolbar.html">
<link rel="import" href="../paper-icon-button/paper-icon-button.html">
<link rel="import" href="../paper-item/paper-item.html">

<link rel="import" href="../iron-icons/iron-icons.html">
<link rel="import" href="../iron-selector/iron-selector.html">

<link rel="import" href="rest-api-property.html">

<link rel="import" href="rest-api-language-selector.html">
<link rel="import" href="rest-api-code-snippet.html">
<link rel="import" href="rest-api-live-demo.html">
<link rel="import" href="rest-api-live-response.html">

<link rel="import" href="rest-api-section.html">
<link rel="import" href="rest-api-doc.html">
<link rel="import" href="rest-api-explanation.html">
<link rel="import" href="rest-api-param.html">
<link rel="import" href="rest-api-header.html">
<link rel="import" href="rest-api-kv-body.html">
<link rel="import" href="rest-api-kv-body.html">

<!--
`rest-api-page` is the containing element for a complete [REST API](https://www.wikiwand.com/en/Representational_state_transfer) documentation.

Example 1 (Get request):

    <rest-api-page base-url="https://httpbin.org" app-name="Example RESTful APP">
      <rest-api-doc title="Get request" endpoint="/get" method="GET">
        <rest-api-param key="param" type="number" values="[1, 2, 3]">Explanation for the param</rest-api-param>
        <rest-api-header key="Content-Type" values='["application/json"]'>Explanation for the header</rest-api-header>
        <rest-api-explanation>Explanation for the endpoint</rest-api-explanation>
      </rest-api-doc>
    </rest-api-page>

Example 2 (Post request w/ body):

    <rest-api-page baseUrl="https://httpbin.org">
      <rest-api-doc title="Post request" endpoint="/post" method="POST">
        <rest-api-kv-body key="key" type="boolean" values="[true, false]">Explanation for the kv-value pair in the body</rest-api-param>
        <rest-api-header key="Content-Type" values='["application/json"]'>Explanation for the header</rest-api-header>
        <rest-api-explanation>Explanation for the endpoint</rest-api-explanation>
      </rest-api-doc>
    </rest-api-page>

Example 3 (Defining sections):

    <rest-api-page baseUrl="https://httpbin.org">
      <rest-api-section heading="A section">
        <rest-api-doc title="Post request" endpoint="/post" method="POST">
          <rest-api-kv-body key="key" type="boolean" values="[true, false]">Explanation for the kv-value pair in the body</rest-api-param>
          <rest-api-header key="Content-Type" values='["application/json"]'>Explanation for the header</rest-api-header>
          <rest-api-explanation>Explanation for the endpoint</rest-api-explanation>
        </rest-api-doc>
      </rest-api-section>
      <rest-api-doc title="Get request" endpoint="/get" method="GET">
        <rest-api-param key="param" type="number" values="[1, 2, 3]">Explanation for the param</rest-api-param>
        <rest-api-header key="Content-Type" values='["application/json"]'>Explanation for the header</rest-api-header>
        <rest-api-explanation>Explanation for the endpoint</rest-api-explanation>
      </rest-api-doc>
    </rest-api-page>

As you maybe realised using a `rest-api-section` works seamlessly with a `rest-api-doc` element directly in the `rest-api-page`.

@group REST Elements
@element rest-api-page
@demo demo/index.html
@hero hero.svg
-->
<dom-module id="rest-api-page">
  <template>
    <style>
      :host {
        /* Default Styling */
        /* TODO: Let user customize styles */
        --primary-color: #9C27B0;
        --accent-color: #448AFF;
        display: block;
        font-family: 'Roboto', 'Noto', sans-serif;
      }
      /* Styling for `Param`, `Headers` and `Body` headings */
      h4 {
        color: #4b4b4b;
      }
      /* Cursor on active paper-items */
      paper-item {
        cursor: pointer;
      }
      /* Style section headings */
      paper-item[disabled] {
        color: #818181;
        font-size: 20px;
        align-items: flex-end;
        min-height: 32px;
        margin-top: 16px;
      }
      /* Background color for `params`, `headers` and `body` doc */
      rest-api-property {
        background: #eee;
      }
      /* Styling for the general doc */
      .general-doc {
        padding: 8px 0;
        font-size: 18px;
      }
      /* Styling for the method */
      .method {
        text-transform: uppercase;
        color: var(--accent-color);
      }
      .dash {
        color: #4a4a4a;
      }
      /* Lighter color for base URL */
      .base-url {
        color: #838383;
      }
      /* Darker color for endpoint after base URL */
      .endpoint {
        font-style: italic;
        color: #4a4a4a;
      }
      /* Styling for the endpoint explanation */
      .explanation {
        margin-top: 16px;
      }
      /* Styling for the endpoint selection */
      paper-header-panel[drawer] {
          background: #f0f0f0;
      }
      .drawer-content {
        height: 100%;
      }
      /* Remove default margin/padding of `paper-toolbar` */
      .toolbar-wrapper {
        position: absolute;
        width: 100%;
        top: 0;
        left: -16px;
        padding: 0 16px;
        height: 100%;
      }
      /* Default styling for main content section */
      .content {
        display: flex;
        height: 100%;
      }
      /* Center endpoint title */
      .endpoint-title {
        align-self: center;
      }
      /* Styling for the documentation section */
      .doc {
        flex: 4;
        display: flex;
        padding: 16px 0;
        flex-direction: column;
      }
      /* Full width `param`, `header` and `body` property doc */
      .doc > :not(rest-api-property):not(paper-icon-button) {
        padding: 0 16px;
      }
      /* Styling for the example section */
      .example {
        flex: 3;
        display: flex;
        background: #616161;
        color: #fff;
        padding: 16px;
        flex-direction: column;
      }
      /* Styling for toolbar documentation section */
      paper-toolbar .doc {
        flex-direction: row;
      }
      /* Styling for toolbar example section */
      paper-toolbar .example {
        flex-direction: row;
        background: #414141;
      }
      /* Scrollbars for documentation and example section */
      .body .doc {
        overflow-y: auto;
      }
      .body .example {
        overflow-y: auto;
        min-height: 500px;
      }
      /* Set width for all children of example section */
      .body .example > * {
        width: calc(100% - 32px);
      }
      /* Styling for small desktop screens */
      @media (max-width: 1000px) {
        /* Double size of main content paper-toolbar */
        paper-header-panel[main] paper-toolbar {
          height: 118px;
        }
        /* Double size of paper-toolbars content area */
        paper-toolbar .content {
          height: 118px;
        }
        /* Put documentation and example section in a single column */
        .content {
          flex-direction: column;
        }
        /* Remove flex and overflow styling from documentation and example section */
        .body .doc {
          flex: none;
          overflow-y: initial;
        }
        .body .example {
          flex: none;
          overflow-y: initial;
        }
      }
    </style>
    <paper-drawer-panel drawer-width="220px">
      <!-- [Drawer start] -->
      <paper-header-panel drawer>
        <!-- [Toolbar start] -->
        <paper-toolbar>
          <div>[[appName]]</div>
        </paper-toolbar>
        <!-- [Toolbar end] -->
        <div class="drawer-content">
          <!-- [Selector start] -->
          <iron-selector selected="0" on-iron-select="_endpointChanged"
                         fallback-selection="0" selectable=".selectable-endpoint">
            <!-- Loop over all direct children of `rest-api-page`: `rest-api-doc` and `rest-api-section` elements -->
            <!-- [Loop start] -->
            <template id="endpointRepeat" is="dom-repeat" items="[[_endpoints]]">
              <!-- [Element is a `rest-api-section` element] -->
              <template is="dom-if" if="[[_isSection(item)]]">
                <!-- Display heading of section in disabled `paper-item` -->
                <paper-item disabled>[[item.heading]]</paper-item>
                <!-- Loop over all `rest-api-doc` elements in `rest-api-section` element -->
                <template is="dom-repeat" items="[[_getDocItems(item)]]" as="endpoint">
                  <paper-item class="selectable-endpoint">[[endpoint.title]]</paper-item>
                </template>
              </template>
              <!-- [Element is a `rest-api-doc` element] -->
              <template is="dom-if" if="[[!_isSection(item)]]">
                <paper-item class="selectable-endpoint">[[item.title]]</paper-item>
              </template>
            </template>
            <!-- [Loop end] -->
          </iron-selector>
          <!-- [Selector end] -->
        </div>
      </paper-header-panel>
      <!-- [Drawer end] -->
      <!-- [Main content start] -->
      <paper-header-panel main>
        <!-- [Toolbar start] -->
        <paper-toolbar>
          <!-- wrapper for removing default padding/margin of `paper-toolbar` -->
          <!-- [wrapper start] -->
          <div class="toolbar-wrapper">
            <!-- split toolbar in 2 parts: one for the whole doc and the other for the examples -->
            <!-- [splitter start] -->
            <div class="content">
              <div class="doc">
                <!-- Show icon if drawer is in narrow layout to toggle drawer -->
                <paper-icon-button icon="menu" paper-drawer-toggle></paper-icon-button>
                <div class="endpoint-title">[[_endpoint.title]]</div>
              </div>
              <div class="example">
                <template is="dom-if" if="[[!noCodeSnippets]]">
                  <!-- Selector for example code snippet language -->
                  <rest-api-language-selector language="{{language}}"></rest-api-language-selector>
                </template>
              </div>
            </div>
            <!-- [splitter end] -->
          </div>
          <!-- [wrapper end] -->
        </paper-toolbar>
        <!-- [Toolbar end] -->
        <!-- split Content section in 2 parts: one for the whole doc and the other for the examples -->
        <!-- [splitter/Content section start] -->
        <div class="body content">
          <!-- [doc start] -->
          <div class="doc">
            <!-- General info about the endpoint -->
            <div class="general-doc">
              <span class="method">[[_endpoint.method]]</span>
              <span class="dash"> - </span>
              <span class="base-url">[[baseUrl]]</span>
              <span class="endpoint">[[_endpoint.endpoint]]</span>
            </div>
            <!-- Explanation of the endpoint -->
            <div class="explanation">[[_endpoint.explanation]]</div>
            <!-- Documentation of the params -->
            <template is="dom-if" if="[[_isSet(_endpoint.params)]]">
              <h4>Params:</h4>
              <template is="dom-repeat" items="[[_endpoint.params]]" as="param">
                <rest-api-property descriptor="[[param]]"></rest-api-property>
              </template>
            </template>
            <!-- Documentation of the body -->
            <template is="dom-if" if="[[_isSet(_endpoint.body)]]">
              <h4>Body:</h4>
              <!-- [If body is provided as key-value pairs] -->
              <template is="dom-if" if="[[_isArray(_endpoint.body)]]">
                <template is="dom-repeat" items="[[_endpoint.body]]" as="kvPair">
                  <rest-api-property descriptor="[[kvPair]]"></rest-api-property>
                </template>
              </template>
              <template is="dom-if" if="[[!_isArray(_endpoint.body)]]">
                <!-- TODO: display value, e.g. as plain text -->
                <!-- Currently not supported. PR's welcome -->
              </template>
            </template>
            <!-- Documentation of the headers -->
            <template is="dom-if" if="[[_isSet(_endpoint.headers)]]">
              <h4>Headers:</h4>
              <template is="dom-repeat" items="[[_endpoint.headers]]" as="header">
                <rest-api-property descriptor="[[header]]"></rest-api-property>
              </template>
            </template>
          </div>
          <!-- [doc end] -->
          <!-- [examples start] -->
          <div class="example">
            <!-- Display code snippets if wanted -->
            <template is="dom-if" if="[[!noCodeSnippets]]">
              <rest-api-code-snippet base-url="[[baseUrl]]" endpoint="[[_endpoint]]" language="[[language]]">
              </rest-api-code-snippet>
            </template>
            <!-- Display live demo with response if wanted -->
            <template id="liveResultWrapper" is="dom-if" if="[[!noLiveDemo]]">
              <rest-api-live-demo base-url="[[baseUrl]]" endpoint="[[_endpoint]]"
                                  on-http-result="_displayResult"></rest-api-live-demo>
              <rest-api-live-response id="restApiLiveResult"></rest-api-live-response>
            </template>
          </div>
          <!-- [examples end] -->
        </div>
        <!-- [splitter/Content section end] -->
      </paper-header-panel>
    </paper-drawer-panel>
    <!-- [Main content end] -->
    <content></content>
  </template>
  <script>
    Polymer({
      is: 'rest-api-page',

      properties: {
        /**
         * The app name the documentation should be for
         */
        appName: {
          type: String,
          value: ''
        },
        /**
         * If no live demo should be shown
         */
        noLiveDemo: {
          type: Boolean,
          value: false
        },
        /**
         * If no code snippets should be shown
         */
        noCodeSnippets: {
          type: Boolean,
          value: false
        },
        /**
         * The base URL of the API
         */
        baseUrl: {
          type: String,
          value: ''
        },
        _endpoints: {
          type: Array
        },
        /**
         * The selected language for the code snippets
         */
        language: {
          type: String,
          value: 'curl'
        }
      },

      ready: function () {
        this.set('_endpoints', []);
        // Recalculate and set endpoints of the API page on changed `innerHTML` of `rest-api-page`
        this._observer = Polymer.dom(this).observeNodes(function (info) {
          this._setEndpoints();
        }.bind(this));
      },

      /**
       * If element is a `rest-api-section` element.
       * @param elem The element to check
       * @returns {boolean} Is a `rest-api-section` element
       * @private
       */
      _isSection: function (elem) {
        return elem.tagName === 'REST-API-SECTION';
      },

      /**
       * Get all `rest-api-doc` elements contained in the node.
       * @param node The node to search for `rest-api-doc` elements
       * @returns {?Array<Node>} An array of nodes contained in the node
       * @private
       */
      _getDocItems: function (node) {
        return node.queryAllEffectiveChildren('rest-api-doc');
      },

      /**
       * Set all `rest-api-doc` and `rest-api-section` elements contained.
       * in the `rest-api-page` to the `_endpoints` property.
       * @private
       */
      _setEndpoints: function () {
        var columns = this.queryAllEffectiveChildren('rest-api-doc, rest-api-section');
        this.set('_endpoints', columns);
      },

      /**
       * Called when the selected endpoint was changed. Set current endpoint to `_endpoint` property.
       * @param e
       * @private
       */
      _endpointChanged: function (e) {
        var element = e.detail.item;
        var data = element._templateInstance.__data__;
        var _endpoint = data.endpoint || data.item;
        this.set('_endpoint', _endpoint);
      },

      /**
       * If `params`, `headers` or `body` is set
       * @param obj Array of `params`, `headers` or `body`
       * @returns {boolean} Is `params`, `headers` or `body` set
       * @private
       */
      _isSet: function (obj) {
        if (obj) {
          if (obj instanceof Array)
            return obj.length > 0;
        }
        return false;
      },

      /**
       * Is param an array
       * @param obj variable to check if it's an array
       * @returns {boolean} Is an array
       * @private
       */
      _isArray: function (obj) {
        return obj && obj instanceof Array;
      },

      /**
       * Called when the live result was changed, display the new result
       * @param e `e.detail.response` is the new HTTP result
       * @private
       */
      _displayResult: function (e) {
        var response = e.detail.response;
        this.$$('#restApiLiveResult').setResponse(response);
      }
    });
  </script>
</dom-module>