Merge branch 'master' into apidocs-dap-updating-link

.eslintrc

@@ -1,6 +1,10 @@
 {
+  "extends": "eslint:recommended",
   "env": {
-    "browser": true
+    "browser": true,
+    "es6": true
   },
-  "extends": "eslint:recommended"
+  "rules": {
+    "max-len": "off"
+  }
 }

APIDOCS.md

@@ -2,30 +2,55 @@
 
 GSA teams can host their API documentation directly on this site if they prefer. 
 
-A live example of this is available here: https://open.gsa.gov/api/sample-api-basic/
+A live example of this is available here:
+- Without the Swagger UI interactive documentation: https://open.gsa.gov/api/sample-api-basic/
+- With  the Swagger UI interactive documentation: https://open.gsa.gov/api/sample-api/
 
-
-## Steps to add API doco
+## Steps to add you API documentation to the GSA API Directory
 
 1. Contact [email protected] and ask for access to manage API docs, sharing your github ID. (Your GitHub ID will have to be in the GSA org.)
 
 2. Create a branch of the site from the `master` branch. Naming convention for new branch: `apidocs-apiname-YYYYMMDD` (replace `apiname` with the name of your API without spaces)
 
-3. In the new branch:
+3A. If you want to use the Swagger UI for interactive documentation
+In the new branch:
+* Copy the file _apidocs/sample-api.md to a file named _apidocs/apiname.md 
+* Create a folder _apidocs/apiname/v1/ (or the correct version).
+* In this new folder, add the OpenAPI specification file, with the name openapi.yaml (if it is OpenAPI v.3) or openapi.json (if it is OpenAPI or Swagger v.2)
+* In the new apinamed.md file, modify the `url: "v1/openapi.yaml",` entry to match the name of your OpenAPI specification file.
+
+3B. If you do _not_ want to use the Swagger UI for interactive documentation
+In the new branch:
 * Copy the file _apidocs/sample-api-basic.md to a file named _apidocs/apiname.md 
 * Create a folder _apidocs/apiname/v1/ (or the correct version).
 * In this new folder, add the OpenAPI specification file, with the name openapi.yaml (if it is OpenAPI v.3) or openapi.json (if it is OpenAPI or Swagger v.2)
 
   Note: the navigation bar is generated from the headings in the markdown file, so those can be customized to meet your needs.
 
-4. When you commit your changes to your repo in github, a preview will be available of the site (with your doco) at this URL:
+4. Edit the apiname.md file with all of the information about your API. When you commit your changes to your repo in github, a preview will be available of the site (with your doco) at this URL after 5 min or so for the preview to build:
 
      https://federalist-proxy.app.cloud.gov/preview/gsa/open-gsa-redesign/[branch-name]/api/[apiname]/
 
 
-5. When you are ready to publish in the API directory, submit a pull request to merge your branch with the `master` branch and @mention Ryan Day or Jeff Fredrickson from the CTO team.
+5. When you are ready to publish in the API directory, submit a pull request to merge your branch with the `master` branch. Post a comment with the preview URL from step 4 and @mention Ryan Day or Jeff Fredrickson from the CTO team. 
+
+6. The CTO team will merge your branch with master, publishing your doco.  At this point, you will see your API doco at: https://open.gsa.gov/api/apiname/
+
+You can also ask the CTO team to update the /_data/api-list.yml, which will add your API to the directory page: https://open.gsa.gov/api/
+
+## Adding swagger UI to your existing API documentation
+
+If you already host your documentation on this site, and you'd like to add the Swagger UI, add this section following the section with the OpenAPI specification:
+
+```
+## API Calls
+
+[Insert descriptive text here]
+
 
-  At this point, you will see your API doco at: https://open.gsa.gov/api/apiname/
+{% include swagger-section-header.html %}
+    url: "v1/[Name of OpenAPI file]", 
+{% include swagger-section-footer.html %}
 
 
-6. The CTO team will merge your branch with master, publishing your doco. They will also update the /_data/api-list.yml, which will add your API to the directory page: https://open.gsa.gov/api/
+<p><small><a href="#">Back to top</a></small></p>```

Gemfile.lock

@@ -127,4 +127,4 @@ DEPENDENCIES
   rake
 
 BUNDLED WITH
-   1.17.2
+   1.17.2

_includes/javascript.html

@@ -1,5 +1,5 @@
 <script src="{{ '/assets/js/lib/jquery-3.3.1.min.js' | prepend: site.baseurl  }}"></script>
-<script async src="{{ '/assets/js/index.js' | prepend: site.baseurl  }}"></script>
+<script src="{{ '/assets/js/lib/details-polyfill.js' | prepend: site.baseurl  }}"></script>
 <script async src="{{ '/assets/uswds/js/uswds.js' | prepend: site.baseurl  }}"></script>
 <script src="https://use.fontawesome.com/2982e64340.js"></script>
 <!-- We participate in the US government's analytics program. See the data at analytics.usa.gov. -->

assets/js/lib/details-polyfill.js

@@ -0,0 +1,73 @@
+void (function (root, factory) {
+  if (typeof define === 'function' && define.amd) define(factory)
+  else if (typeof exports === 'object') module.exports = factory()
+  else factory()
+}(this, function () {
+  var DETAILS = 'details'
+  var SUMMARY = 'summary'
+
+  var supported = checkSupport()
+  if (supported) return
+
+  // Add a classname
+  document.documentElement.className += ' no-details'
+
+  window.addEventListener('click', clickHandler)
+
+  injectStyle('details-polyfill-style',
+    'html.no-details ' + DETAILS + ':not([open]) > :not(' + SUMMARY + ') { display: none; }\n' +
+    'html.no-details ' + DETAILS + ' > ' + SUMMARY + ':before { content: "\u25b6"; display: inline-block; font-size: .8em; width: 1.5em; }\n' +
+    'html.no-details ' + DETAILS + '[open] > ' + SUMMARY + ':before { content: "\u25bc"; }')
+
+  /*
+   * Click handler for `<summary>` tags
+   */
+
+  function clickHandler (e) {
+    if (e.target.nodeName.toLowerCase() === 'summary') {
+      var details = e.target.parentNode
+      if (!details) return
+
+      if (details.getAttribute('open')) {
+        details.open = false
+        details.removeAttribute('open')
+      } else {
+        details.open = true
+        details.setAttribute('open', 'open')
+      }
+    }
+  }
+
+  /*
+   * Checks for support for `<details>`
+   */
+
+  function checkSupport () {
+    var el = document.createElement(DETAILS)
+    if (!('open' in el)) return false
+
+    el.innerHTML = '<' + SUMMARY + '>a</' + SUMMARY + '>b'
+    document.body.appendChild(el)
+
+    var diff = el.offsetHeight
+    el.open = true
+    var result = (diff != el.offsetHeight)
+
+    document.body.removeChild(el)
+    return result
+  }
+
+  /*
+   * Injects styles (idempotent)
+   */
+
+  function injectStyle (id, style) {
+    if (document.getElementById(id)) return
+
+    var el = document.createElement('style')
+    el.id = id
+    el.innerHTML = style
+
+    document.getElementsByTagName('head')[0].appendChild(el)
+  }
+})); // eslint-disable-line semi

assets/js/search.js

@@ -2,32 +2,34 @@
 
 (function(baseurl) {
   if (baseurl === undefined) {
-    baseurl = "";
+    baseurl = '';
   }
 
+  /**
+   * Initialize the search page content.
+   */
   function initSearchPage() {
-
-    var searchTerm = getSearchQuery();
+    const searchTerm = getSearchQuery();
     if (searchTerm) {
-      var url = baseurl + "/api/v1/pages.json";
-      var xhr = new XMLHttpRequest();
-      xhr.open("GET", url, true);
-      xhr.onload = function () {
+      const url = baseurl + '/api/v1/pages.json';
+      const xhr = new XMLHttpRequest();
+      xhr.open('GET', url, true);
+      xhr.onload = function() {
         if (xhr.readyState === 4) {
           if (xhr.status === 200) {
-            var pagesData = JSON.parse(xhr.responseText);
+            const pagesData = JSON.parse(xhr.responseText);
             search(pagesData.entries, searchTerm);
           } else {
-            var $results = document.getElementById("search-results");
-            var output = '<p>There was an error while searching. Please try again.</p>';
+            const $results = document.getElementById('search-results');
+            let output = '<p>There was an error while searching. Please try again.</p>';
             output += '<p>' + xhr.statusText + '</p>';
             $results.innerHTML = output;
           }
         }
       };
-      xhr.onerror = function () {
-        var $results = document.getElementById("search-results");
-        var output = '<p>There was an error while searching. Please try again.</p>';
+      xhr.onerror = function() {
+        const $results = document.getElementById('search-results');
+        let output = '<p>There was an error while searching. Please try again.</p>';
         output += '<p>' + xhr.statusText + '</p>';
         $results.innerHTML = output;
       };
@@ -36,21 +38,16 @@
   }
 
   function search(pages, searchTerm) {
-    document.getElementById("search-field").setAttribute("value", searchTerm);
-    var lunrIndex = lunr(function () {
-      this.ref("id");
-      this.field("title", { boost: 10 });
-      this.field("body");
-      this.field("category");
-      this.field("tags");
+    document.getElementById('search-field').setAttribute('value', searchTerm);
+    const lunrIndex = lunr(function() {
+      this.ref('id');
+      this.field('title', { boost: 10 });
+      this.field('body');
+      this.field('category');
+      this.field('tags');
     });
 
-
-    for (var i in searchData){
-      pages.push(searchData[i]);
-    }
-
-    for (var index in pages) {
+    for (let index in pages) {
       lunrIndex.add({
         id: index,
         title: pages[index].title,
@@ -60,34 +57,31 @@
       });
     }
 
-    var matches = lunrIndex.search(searchTerm);
+    const matches = lunrIndex.search(searchTerm);
 
-    displayResults(matches, pages, searchData);
+    displayResults(matches, pages);
   }
 
   function getSearchQuery() {
-    var rawParams = window.location.search.replace(/^\?/, "");
-    var params = rawParams.split("&");
-    for (var index in params) {
-      var keyValuePair = params[index].split("=");
-      var key = keyValuePair[0];
-      var value = keyValuePair[1];
-      if (key === "search") {
-        return decodeURIComponent(value.replace(/\+/g, " "));
+    const rawParams = window.location.search.replace(/^\?/, '');
+    const params = rawParams.split('&');
+    for (let index in params) {
+      const keyValuePair = params[index].split('=');
+      const key = keyValuePair[0];
+      const value = keyValuePair[1];
+      if (key === 'search') {
+        return decodeURIComponent(value.replace(/\+/g, ' '));
       }
     }
   }
 
-  function displayResults(matches, pages, searchData) {
-
-    var $results = document.getElementById("search-results");
+  function displayResults(matches, pages) {
+    const $results = document.getElementById('search-results');
     if (matches.length > 0) {
-      var output = '<ul class="usa-unstyled-list">';
-      for (var index in matches) {
-
-        var page = pages[matches[index].ref];
-
-        var icon = '<i class="fa fa-bar-chart flag"></i>';
+      let output = '<ul class="usa-unstyled-list">';
+      for (let index in matches) {
+        const page = pages[matches[index].ref];
+        let icon = '<i class="fa fa-bar-chart flag"></i>';
 
         switch (page.category) {
           case 'Data':
@@ -109,11 +103,11 @@
             icon = '<i class="fa fa-file-text flag"></i>';
         }
 
-        var title = '<h3>' + '<a href="' + page.url + '">' + page.title + '</a></h3>';
-        var copy = '<p>' + page.body.substring(0, 200) + ' ...</p>';
-        var outputTags = '';
+        const title = '<h3>' + '<a href="' + page.url + '">' + page.title + '</a></h3>';
+        const copy = '<p>' + page.body.substring(0, 200) + ' ...</p>';
+        let outputTags = '';
         //loop through tags and parse
-        for( var tag in page.tags ){
+        for(let tag in page.tags ){
           outputTags  += '<span class="usa-label">' + page.tags[tag] + '</span>';
         }
 
@@ -128,5 +122,4 @@
   }
 
   initSearchPage();
-
 })(window.baseurl);