feat(ghe): add ghe-2.15 openapi docs (#453)

* add openapi root doc for ghe-2.15
* generate operations for ghe-2.15
* make all ghe-2.15 tests pass w/ current openapi-compatible route-building rules
  * more strictly determine openapi-compliant defaults
  * parse object[] parameters' descriptions above definition table
  * clean up badly parsed string/array defaults
  * add missed enums
* update ghe-2.15 caches

cache/ghe-2.15/enterprise/2.15/v3/activity/events/types/checkrunevent.html

@@ -20,7 +20,7 @@ <h3>
 <tr>
 <td><code>action</code></td>
 <td><code>string</code></td>
-<td>The action performed. Can be one of: <br>* <code>created</code> - A new check run was created.<br>* <code>completed</code> - The <code>status</code> of the check run is <code>completed</code>.<br>* <code>rerequested</code> - Someone requested to re-run your check run.<br>* <code>requested_action</code> - Someone requested that an action be taken. For example, this <code>action</code> will be sent if someone clicks a &quot;Fix it&quot; button in the UI. See <a href="/changes/2018-05-23-request-actions-on-checks/">Request further actions from a check run</a> for details.</td>
+<td>The action performed. Can be one of: <br>* <code>created</code> - A new check run was created.<br>* <code>completed</code> - The <code>status</code> of the check run is <code>completed</code>.<br>* <code>rerequested</code> - Someone requested to re-run your check run.<br>* <code>requested_action</code> - Someone requested that an action be taken. For example, this <code>action</code> will be sent if someone clicks a &quot;Fix it&quot; button in the UI. To learn more about check runs and requested actions, see &quot;<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>.&quot;</td>
 </tr>
 <tr>
 <td><code>check_run</code></td>

cache/ghe-2.15/enterprise/2.15/v3/activity/events/types/index.html

@@ -324,7 +324,7 @@ <h3>
 <tr>
 <td><code>action</code></td>
 <td><code>string</code></td>
-<td>The action performed. Can be one of: <br>* <code>created</code> - A new check run was created.<br>* <code>completed</code> - The <code>status</code> of the check run is <code>completed</code>.<br>* <code>rerequested</code> - Someone requested to re-run your check run.<br>* <code>requested_action</code> - Someone requested that an action be taken. For example, this <code>action</code> will be sent if someone clicks a "Fix it" button in the UI. See <a href="/changes/2018-05-23-request-actions-on-checks/">Request further actions from a check run</a> for details.</td>
+<td>The action performed. Can be one of: <br>* <code>created</code> - A new check run was created.<br>* <code>completed</code> - The <code>status</code> of the check run is <code>completed</code>.<br>* <code>rerequested</code> - Someone requested to re-run your check run.<br>* <code>requested_action</code> - Someone requested that an action be taken. For example, this <code>action</code> will be sent if someone clicks a "Fix it" button in the UI. To learn more about check runs and requested actions, see "<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>."</td>
 </tr>
 <tr>
 <td><code>check_run</code></td>

cache/ghe-2.15/enterprise/2.15/v3/checks/index.html

@@ -347,6 +347,7 @@ <h3>
     </div>
   </div>
 </div>
+<p>For an example of how to use the Checks API with a GitHub App, see "<a href="/enterprise/2.15/apps/quickstart-guides/creating-ci-tests-with-the-checks-api/">Creating CI tests with the Checks API</a>."</p>
 <h2>
 <a id="check-runs-api" class="anchor" href="#check-runs-api" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><a href="/enterprise/2.15/v3/checks/runs/">Check runs API</a>
 </h2>

cache/ghe-2.15/enterprise/2.15/v3/checks/runs/create-a-check-run.html

@@ -79,10 +79,11 @@ <h3>
 <tr>
 <td><code>actions</code></td>
 <td><code>array of objects</code></td>
-<td>Possible further actions the integrator can perform, which a user may trigger. Each action includes a <code>label</code>, <code>identifier</code> and <code>description</code>. A maximum of three actions are accepted. See the <a href="#actions-object"><code>actions</code> object</a> description.</td>
+<td>Displays a button on GitHub that can be clicked to alert your app to do additional tasks. For example, a code linting app can display a button that automatically fixes detected errors. The button created in this object is displayed after the check run completes. When a user clicks the button, GitHub sends the <a href="/enterprise/2.15/v3/activity/events/types/#checkrunevent"><code>check_run.requested_action</code> webhook</a> to your app. Each action includes a <code>label</code>, <code>identifier</code> and <code>description</code>. A maximum of three actions are accepted. See the <a href="#actions-object"><code>actions</code> object</a> description.</td>
 </tr>
 </tbody>
 </table>
+<p>To learn more about check runs and requested actions, see &quot;<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>.&quot;</p>
 <h4>
 <a id="output-object" class="anchor" href="#output-object" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>output</code> object</h4>
 <table>
@@ -218,6 +219,7 @@ <h4>
 </table>
 <h4>
 <a id="actions-object" class="anchor" href="#actions-object" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>actions</code> object</h4>
+<p>To learn more about check runs and requested actions, see &quot;<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>.&quot;</p>
 <table>
 <thead>
 <tr>

cache/ghe-2.15/enterprise/2.15/v3/checks/runs/index.html

@@ -274,6 +274,20 @@ <h1>
 <p>A check can also be manually re-run in the GitHub UI. See "<a href="https://help.github.com/articles/about-status-checks#checks">About status checks</a>" for more details. When this occurs, the GitHub App that created the check run will receive the <a href="/enterprise/2.15/v3/activity/events/types/#checkrunevent"><code>check_run</code></a> webhook requesting a new check run. If you create a check run without creating a check suite, GitHub creates the check suite for you automatically.</p>
 <p>Write permission for the Checks API is only available to GitHub Apps. OAuth Apps and authenticated users can view check runs and check suites, but they are not able to create them. If you aren't building a GitHub App, you might be interested in the <a href="/enterprise/2.15/v3/repos/statuses/">Statuses API</a>.</p>
 <p>To use the check runs API, the GitHub App must have the <code>checks:write</code> permission and can also subscribe to the <a href="/enterprise/2.15/v3/activity/events/types/#checkrunevent">check_run</a> webhook.</p>
+<h3>
+<a id="check-runs-and-requested-actions" class="anchor" href="#check-runs-and-requested-actions" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Check runs and requested actions</h3>
+<p>When you set up a check run with requested actions (not to be confused with GitHub Actions), you can display a button in the pull request view on GitHub that allows people to request your GitHub App to perform additional tasks.</p>
+<p>For example, a code linting app could use requested actions to display a button in a pull request to automatically fix detected syntax errors. </p>
+<p>To create a button that can request additional actions from your app, use the <a href="#actions-object"><code>actions</code> object</a> when you <a href="/enterprise/2.15/v3/checks/runs/#create-a-check-run">Create a check run</a>. For example, the <code>actions</code> object below displays a button in a pull request with the label "Fix this." The button appears after the check run completes.</p>
+<pre class="highlight highlight-json"><code><span class="w">  </span><span class="s2">"actions"</span><span class="err">:</span><span class="w"> </span><span class="p">[{</span><span class="w">
+      </span><span class="nt">"label"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Fix this"</span><span class="p">,</span><span class="w">
+      </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Let us fix that for you"</span><span class="p">,</span><span class="w">
+      </span><span class="nt">"identifier"</span><span class="p">:</span><span class="w"> </span><span class="s2">"fix_errors"</span><span class="w">
+    </span><span class="p">}]</span><span class="w">
+</span></code></pre>
+<p><img src="https://github-images.s3.amazonaws.com/enterprise/developer-site/2.15/assets/images/github-apps/github_apps_checks_fix_this_button.png" alt="Check run requested action button"></p>
+<p>When a user clicks the button, GitHub sends the <a href="/enterprise/2.15/v3/activity/events/types/#checkrunevent"><code>check_run.requested_action</code> webhook</a> to your app. When your app receives a <code>check_run.requested_action</code> webhook event, it can look for the <code>requested_action.identifier</code> key in the webhook payload to determine which button was clicked and perform the requested task.</p>
+<p>For a detailed example of how to set up requested actions with the Checks API, see "<a href="/enterprise/2.15/apps/quickstart-guides/creating-ci-tests-with-the-checks-api/#part-2-creating-the-octo-rubocop-ci-test">Creating CI tests with the Checks API</a>."</p>
 <h2>
 <a id="create-a-check-run" class="anchor" href="#create-a-check-run" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Create a check run<a href="/enterprise/2.15/apps/" class="tooltip-link github-apps-marker octicon octicon-info" title="Enabled for GitHub Apps"></a>
 </h2>
@@ -355,10 +369,11 @@ <h3>
 <tr>
 <td><code>actions</code></td>
 <td><code>array of objects</code></td>
-<td>Possible further actions the integrator can perform, which a user may trigger. Each action includes a <code>label</code>, <code>identifier</code> and <code>description</code>. A maximum of three actions are accepted. See the <a href="#actions-object"><code>actions</code> object</a> description.</td>
+<td>Displays a button on GitHub that can be clicked to alert your app to do additional tasks. For example, a code linting app can display a button that automatically fixes detected errors. The button created in this object is displayed after the check run completes. When a user clicks the button, GitHub sends the <a href="/enterprise/2.15/v3/activity/events/types/#checkrunevent"><code>check_run.requested_action</code> webhook</a> to your app. Each action includes a <code>label</code>, <code>identifier</code> and <code>description</code>. A maximum of three actions are accepted. See the <a href="#actions-object"><code>actions</code> object</a> description.</td>
 </tr>
 </tbody>
 </table>
+<p>To learn more about check runs and requested actions, see "<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>."</p>
 <h4>
 <a id="output-object" class="anchor" href="#output-object" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>output</code> object</h4>
 <table>
@@ -494,6 +509,7 @@ <h4>
 </table>
 <h4>
 <a id="actions-object" class="anchor" href="#actions-object" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>actions</code> object</h4>
+<p>To learn more about check runs and requested actions, see "<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>."</p>
 <table>
 <thead>
 <tr>
@@ -952,6 +968,7 @@ <h4>
 </table>
 <h4>
 <a id="actions-object-1" class="anchor" href="#actions-object-1" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>actions</code> object</h4>
+<p>To learn more about check runs and requested actions, see "<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>."</p>
 <table>
 <thead>
 <tr>

cache/ghe-2.15/enterprise/2.15/v3/checks/runs/update-a-check-run.html

@@ -210,6 +210,7 @@ <h4>
 </table>
 <h4>
 <a id="actions-object-1" class="anchor" href="#actions-object-1" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><code>actions</code> object</h4>
+<p>To learn more about check runs and requested actions, see &quot;<a href="/enterprise/2.15/v3/checks/runs/#check-runs-and-requested-actions">Check runs and requested actions</a>.&quot;</p>
 <table>
 <thead>
 <tr>

cache/ghe-2.15/enterprise/2.15/v3/search/index.html

@@ -269,7 +269,7 @@ <h1>
 <li><a href="#text-match-metadata" id="markdown-toc-text-match-metadata">Text match metadata</a></li>
 </ul>
 <p>The Search API helps you search for the specific item you want to find. For example, you can find a user or a specific file in a repository. Think of it the way you think of performing a search on Google. It's designed to help you find the one result you're looking for (or maybe the few results you're looking for). Just like searching on Google, you sometimes want to see a few pages of search results so that you can find the item that best meets your needs. To satisfy that need, the GitHub Enterprise Search API provides <strong>up to 1,000 results for each search</strong>.</p>
-<p>You can narrow your search using queries, also known as search qualifiers or query parameters. If only some search queries are successful, then you will see a partially successful response with an empty list for unsuccessful queries.</p>
+<p>You can narrow your search using queries. To learn more about the search query syntax, see "<a href="/enterprise/2.15/v3/search/#constructing-a-search-query">Constructing a search query</a>."</p>
 <h3>
 <a id="ranking-search-results" class="anchor" href="#ranking-search-results" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Ranking search results</h3>
 <p>Unless another sort option is provided as a query parameter, results are sorted
@@ -304,34 +304,12 @@ <h3>
 quantities, dates, or to exclude results, see "<a href="https://help.github.com/articles/understanding-the-search-syntax/">Understanding the search syntax</a>."</p>
 <h3>
 <a id="limitations-on-query-length" class="anchor" href="#limitations-on-query-length" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Limitations on query length</h3>
-<p>The Search API does not support queries that are longer than 256 characters (not including operators or qualifiers) and will return an error.</p>
-<pre><code>{
-  "message": "Validation Failed",
-  "errors": [
-    {
-      "message": "The search is longer than 256 characters.",
-      "resource": "Search",
-      "field": "q",
-      "code": "invalid"
-    }
-  ],
-  "documentation_url": "https://developer.github.com/v3/search/"
-}
-</code></pre>
-<p>Also, a query using more than five <code>AND</code>, <code>OR</code>, or <code>NOT</code> operators will return an error.</p>
-<pre><code>{
-  "message": "Validation Failed",
-  "errors": [
-    {
-      "message": "More than five AND / OR / NOT operators were used.",
-      "resource": "Search",
-      "field": "q",
-      "code": "invalid"
-    }
-  ],
-  "documentation_url": "https://developer.github.com/v3/search/"
-}
-</code></pre>
+<p>The Search API does not support queries that:</p>
+<ul>
+<li>are longer than 256 characters (not including operators or qualifiers).</li>
+<li>have more than five <code>AND</code>, <code>OR</code>, or <code>NOT</code> operators.</li>
+</ul>
+<p>These search queries will return a "Validation failed" error message.</p>
 <h3>
 <a id="timeouts-and-incomplete-results" class="anchor" href="#timeouts-and-incomplete-results" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Timeouts and incomplete results</h3>
 <p>To keep the Search API fast for everyone, we limit how long any individual query
@@ -341,21 +319,10 @@ <h3>
 <p>Reaching a timeout does not necessarily mean that search results are incomplete.
 More results might have been found, but also might not.</p>
 <h3>
-<a id="permissions-failure-or-an-empty-list" class="anchor" href="#permissions-failure-or-an-empty-list" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Permissions failure or an empty list</h3>
-<p>You need to successfully authenticate and have access to the repositories in your search queries, otherwise, you'll see a <code>422 Unprocessible Entry</code> error. For example, your search will fail if your query includes <code>repo:</code> or <code>user:</code> or <code>org:</code> qualifiers and doesn't match the resources that you have access to when you sign in on GitHub.</p>
-<pre><code>{
-  "message": "Validation Failed",
-  "errors": [
-    {
-      "message": "The listed users and repositories cannot be searched either because the resources do not exist or you do not have permission to view them.",
-      "resource": "Search",
-      "field": "q",
-      "code": "invalid"
-    }
-  ],
-  "documentation_url": "https://developer.github.com/v3/search/"
-}
-</code></pre>
+<a id="access-errors-or-missing-search-results" class="anchor" href="#access-errors-or-missing-search-results" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Access errors or missing search results</h3>
+<p>You need to successfully authenticate and have access to the repositories in your search queries, otherwise, you'll see a <code>422 Unprocessible Entry</code> error with a "Validation Failed" message. For example, your search will fail if your query includes <code>repo:</code>, <code>user:</code>, or <code>org:</code> qualifiers that request resources that you don't have access to when you sign in on GitHub.</p>
+<p>When your search query requests multiple resources, the response will only contain the resources that you have access to and will <strong>not</strong> provide an error message listing the resources that were not returned. </p>
+<p>For example, if your search query searches for the <code>octocat/test</code> and <code>codertocat/test</code> repositories, but you only have access to <code>octocat/test</code>, your response will show search results for <code>octocat/test</code> and nothing for <code>codertocat/test</code>. This behavior mimics how search works on GitHub.</p>
 <h2>
 <a id="search-repositories" class="anchor" href="#search-repositories" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Search repositories<a href="/enterprise/2.15/apps/" class="tooltip-link github-apps-marker octicon octicon-info" title="Enabled for GitHub Apps"></a>
 </h2>