Merge branch 'main' into sticky-github-logo-header

github · Sep 28, 2020 · 67f9bb3 · 67f9bb3
2 parents 2cc72fc + c13fcf7
commit 67f9bb3
Show file tree

Hide file tree

Showing 4 changed files with 159 additions and 521 deletions.
diff --git a/includes/rest_operation.html b/includes/rest_operation.html
@@ -21,23 +21,39 @@ <h4 id="{{operation.slug}}--parameters">
           </tr>
         </thead>
         <tbody>
-          {% for param in operation.parameters %}
-            <tr>
-              <td><code>{{ param.name }}</code></td>
-              <td class="opacity-70">{{ param.schema.type }}</td>
-              <td class="opacity-70">{{ param.in }}</td>
-              <td class="opacity-70">
-                {{ param.descriptionHTML }}
-                {% if param.name == 'accept' and param.in == 'header' and operation.x-github.previews.size > 0 %}
+          <!-- 
+            Previews require an `accept` header. These used to be documented
+            as `operation.parameters` but have moved to `operation.x-github.previews`
+          -->
+          <tr>
+            <td><code>accept</code></td>
+            <td class="opacity-70">string</td>
+            <td class="opacity-70">header</td>
+            <td class="opacity-70">
+              <p>
+                {% if operation.hasRequiredPreviews %}
+                  This API is under preview and subject to change.
+                {% else %}
+                  Setting to <code>application/vnd.github.v3+json</code> is recommended.
+                {% endif %}
+                {% if operation.x-github.previews.size > 0 %}
                   <a href="#{{operation.slug}}-preview-notices">
                     {% if operation.x-github.previews.size > 1 %}
-                      {{ site.data.ui.products.rest.reference.see_preview_notices }}.
+                      {{ site.data.ui.products.rest.reference.see_preview_notices }}
                     {% else %}
-                      {{ site.data.ui.products.rest.reference.see_preview_notice }}.
+                      {{ site.data.ui.products.rest.reference.see_preview_notice }}
                     {% endif %}
                   </a>
                 {% endif %}
-              </td>
+              </p>
+            </td>
+          </tr>
+          {% for param in operation.parameters %}
+            <tr>
+              <td><code>{{ param.name }}</code></td>
+              <td class="opacity-70">{{ param.schema.type }}</td>
+              <td class="opacity-70">{{ param.in }}</td>
+              <td class="opacity-70">{{ param.descriptionHTML }}</td>
             </tr>
           {% endfor %}
           {% for bodyParam in operation.bodyParameters %}

diff --git a/lib/rest.js b/lib/rest.js
@@ -1,4 +1,4 @@
-const { chain, union, flatten, groupBy } = require('lodash')
+const { chain, get, union, flatten, groupBy } = require('lodash')
 const { supported } = require('./enterprise-server-releases')
 const operations = require('@github/rest-api-operations')
 // TODO need to update this to the new versions in coordination with openAPI
@@ -16,6 +16,13 @@ const dotcomCategories = getCategories(operations.dotcom)
 const enterpriseCategories = flatten(supported.map(v => getCategories(operations[v])))
 const categories = union(dotcomCategories, enterpriseCategories)
 
+// Attach convenience properties to each operation that can't easily be created in Liquid
+allVersions.forEach(currentVersion => {
+  operations[currentVersion].forEach(operation => {
+    operation.hasRequiredPreviews = get(operation, 'x-github.previews', []).some(preview => preview.required)
+  })
+})
+
 // This is a collection of operations that have `enabledForApps = true`
 // It's grouped by resource title to make rendering easier
 const operationsEnabledForApps = allVersions.reduce((acc, currentVersion) => {