Merge pull request #450 from github/openapi-update-066f1a0bb6e6aceb6f2e2cea1257f7194d455aa67febc609d9b824c918f15c26

Update OpenAPI Descriptions

Author: nickfloyd

descriptions/api.github.com/api.github.com.json

@@ -6264,22 +6264,9 @@ paths:
                     html_url: https://www.contributor-covenant.org/version/2/0/code_of_conduct/
         '304':
           description: Not modified
-        '415':
-          description: Preview header missing
-          content: *30
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: true
-        previews:
-        - required: true
-          name: scarlet-witch
-          note: |-
-            The Codes of Conduct API is currently available for developers to preview.
-
-            To access the API during the preview period, you must provide a custom [media type](https://docs.github.com/[email protected]/rest/overview/media-types) in the `Accept` header:
-            ```shell
-            application/vnd.github.scarlet-witch-preview+json
-            ```
         category: codes-of-conduct
         subcategory: 
   "/codes_of_conduct/{key}":
@@ -6370,22 +6357,9 @@ paths:
           content: *25
         '304':
           description: Not modified
-        '415':
-          description: Preview header missing
-          content: *30
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: true
-        previews:
-        - required: true
-          name: scarlet-witch
-          note: |-
-            The Codes of Conduct API is currently available for developers to preview.
-
-            To access the API during the preview period, you must provide a custom [media type](https://docs.github.com/[email protected]/rest/overview/media-types) in the `Accept` header:
-            ```shell
-            application/vnd.github.scarlet-witch-preview+json
-            ```
         category: codes-of-conduct
         subcategory: 
   "/emojis":
@@ -17574,26 +17548,6 @@ paths:
                     - key
                     - name
                     - html_url
-                  security_and_analysis:
-                    nullable: true
-                    type: object
-                    properties:
-                      advanced_security:
-                        type: object
-                        properties:
-                          status:
-                            type: string
-                            enum:
-                            - enabled
-                            - disabled
-                      secret_scanning:
-                        type: object
-                        properties:
-                          status:
-                            type: string
-                            enum:
-                            - enabled
-                            - disabled
                 required: &153
                 - archive_url
                 - assignees_url
@@ -51709,10 +51663,10 @@ paths:
         subcategory: management-console
     post:
       summary: Enable or disable maintenance mode
-      description: |-
-        The possible values for `enabled` are `true` and `false`. When it's `false`, the attribute `when` is ignored and the maintenance mode is turned off. `when` defines the time period when the maintenance was enabled.
-
-        The possible values for `when` are `now` or any date parseable by [mojombo/chronic](https://github.com/mojombo/chronic).
+      description: "**Note:** The request body for this operation must be submitted
+        as `application/x-www-form-urlencoded` data. You can submit a parameter value
+        as a string, or you can use a tool such as `curl` to submit a parameter value
+        as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode)."
       operationId: enterprise-admin/enable-or-disable-maintenance-mode
       tags:
       - enterprise-admin
@@ -51732,15 +51686,22 @@ paths:
                   value: *336
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties:
                 maintenance:
                   type: string
-                  description: A JSON string with the attributes `enabled` and `when`.
+                  description: |-
+                    A JSON string with the attributes `enabled` and `when`.
+
+                    The possible values for `enabled` are `true` and `false`. When it's `false`, the attribute `when` is ignored and the maintenance mode is turned off. `when` defines the time period when the maintenance was enabled.
+
+                    The possible values for `when` are `now` or any date parseable by [mojombo/chronic](https://github.com/mojombo/chronic).
               required:
               - maintenance
+            example:
+              maintenance: '{"enabled":true, "when":"now"}'
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: false
@@ -52192,7 +52153,10 @@ paths:
         subcategory: management-console
     put:
       summary: Set settings
-      description: For a list of the available settings, see the [Get settings endpoint](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#get-settings).
+      description: |-
+        For a list of the available settings, see the [Get settings endpoint](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#get-settings).
+
+        **Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).
       operationId: enterprise-admin/set-settings
       tags:
       - enterprise-admin
@@ -52204,16 +52168,19 @@ paths:
           description: Response
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties:
                 settings:
                   type: string
                   description: A JSON string with the new settings. Note that you
-                    only need to pass the specific settings you want to modify.
+                    only need to pass the specific settings you want to modify. For
+                    a list of the available settings, see the [Get settings endpoint](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#get-settings).
               required:
               - settings
+            example:
+              settings: '{ "enterprise": { "public_pages": true }}'
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: false
@@ -52259,7 +52226,10 @@ paths:
         subcategory: management-console
     post:
       summary: Add an authorized SSH key
-      description: ''
+      description: "**Note:** The request body for this operation must be submitted
+        as `application/x-www-form-urlencoded` data. You can submit a parameter value
+        as a string, or you can use a tool such as `curl` to submit a parameter value
+        as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode)."
       operationId: enterprise-admin/add-authorized-ssh-key
       tags:
       - enterprise-admin
@@ -52281,15 +52251,17 @@ paths:
                   value: *338
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties:
                 authorized_key:
                   type: string
-                  description: The path to the public SSH key.
+                  description: The public SSH key.
               required:
               - authorized_key
+            example:
+              authorized_key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: false
@@ -52298,7 +52270,10 @@ paths:
         subcategory: management-console
     delete:
       summary: Remove an authorized SSH key
-      description: ''
+      description: "**Note:** The request body for this operation must be submitted
+        as `application/x-www-form-urlencoded` data. You can submit a parameter value
+        as a string, or you can use a tool such as `curl` to submit a parameter value
+        as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode)."
       operationId: enterprise-admin/remove-authorized-ssh-key
       tags:
       - enterprise-admin
@@ -52320,15 +52295,17 @@ paths:
                   value: *338
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties:
                 authorized_key:
                   type: string
-                  description: The path to the public SSH key.
+                  description: The public SSH key.
               required:
               - authorized_key
+            example:
+              authorized_key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCssTL/Vtu/ODLTj0VtZoRAbvf7uiv5997GyDq0MoAZUjb5jmA5wYe2/wF6sFuhiZTnZoF1ZtCHunPp0hM/GHrn6VySBhNncx14YO8FPt1CIhEeRMSEjUK9cY3xAbS365oXY8vnUHJsS9+1tr/2bx/+4NJfcUt/Ezf1OR/0LStQXw==
       x-github:
         githubCloudOnly: false
         enabledForGitHubApps: false
@@ -52339,16 +52316,16 @@ paths:
     post:
       summary: Create a GitHub license
       description: |-
-        When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license:
+        When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.
 
-        Note that you need to POST to [`/setup/api/configure`](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#start-a-configuration-process) to start the actual configuration process.
+        Note that you need to `POST` to [`/setup/api/configure`](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#start-a-configuration-process) to start the actual configuration process.
 
         When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:
 
         1.  If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
         2.  If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.
 
-        For a list of the available settings, see the [Get settings endpoint](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#get-settings).
+        **Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).
       operationId: enterprise-admin/create-enterprise-server-license
       tags:
       - enterprise-admin
@@ -52360,7 +52337,7 @@ paths:
           description: Response
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties:
@@ -52375,7 +52352,8 @@ paths:
                 settings:
                   type: string
                   description: An optional JSON string containing the installation
-                    settings.
+                    settings. For a list of the available settings, see the [Get settings
+                    endpoint](https://docs.github.com/[email protected]/rest/reference/enterprise-admin#get-settings).
               required:
               - license
       x-github:
@@ -52387,8 +52365,10 @@ paths:
   "/setup/api/upgrade":
     post:
       summary: Upgrade a license
-      description: 'This API upgrades your license and also triggers the configuration
-        process:'
+      description: |-
+        This API upgrades your license and also triggers the configuration process.
+
+        **Note:** The request body for this operation must be submitted as `application/x-www-form-urlencoded` data. You can submit a parameter value as a string, or you can use a tool such as `curl` to submit a parameter value as the contents of a text file. For more information, see the [`curl` documentation](https://curl.se/docs/manpage.html#--data-urlencode).
       operationId: enterprise-admin/upgrade-license
       tags:
       - enterprise-admin
@@ -52400,7 +52380,7 @@ paths:
           description: Response
       requestBody:
         content:
-          application/json:
+          application/x-www-form-urlencoded:
             schema:
               type: object
               properties: