Update OpenAPI 3.1 Descriptions

github · Dec 20, 2023 · cfa2024 · cfa2024
1 parent 908cb28
commit cfa2024
Show file tree

Hide file tree

Showing 16 changed files with 328 additions and 112 deletions.
diff --git a/descriptions-next/api.github.com/api.github.com.2022-11-28.json b/descriptions-next/api.github.com/api.github.com.2022-11-28.json
@@ -15058,7 +15058,7 @@
     "/orgs/{org}/properties/schema": {
       "get": {
         "summary": "Get all custom properties for an organization",
-        "description": "Gets all custom properties defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Gets all custom properties defined for an organization.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15107,7 +15107,7 @@
       },
       "patch": {
         "summary": "Create or update custom properties for an organization",
-        "description": "Creates new or updates existing custom properties defined for an organization in a batch.\nOnly organization owners (or users with the proper permissions granted by them) can update these properties",
+        "description": "Creates new or updates existing custom properties defined for an organization in a batch.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15210,7 +15210,7 @@
     "/orgs/{org}/properties/schema/{custom_property_name}": {
       "get": {
         "summary": "Get a custom property for an organization",
-        "description": "Gets a custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Gets a custom property that is defined for an organization.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15259,7 +15259,7 @@
       },
       "put": {
         "summary": "Create or update a custom property for an organization",
-        "description": "Creates a new or updates an existing custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Creates a new or updates an existing custom property that is defined for an organization.\n\nTo use this endpoint, the authenticated user must be one of:\n- An administrator for the organization.\n- A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15376,7 +15376,7 @@
       },
       "delete": {
         "summary": "Remove a custom property for an organization",
-        "description": "Removes a custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Removes a custom property that is defined for an organization.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15415,7 +15415,7 @@
     "/orgs/{org}/properties/values": {
       "get": {
         "summary": "List custom property values for organization repositories",
-        "description": "Lists organization repositories with all of their custom property values.\nOrganization members can read these properties.",
+        "description": "Lists organization repositories with all of their custom property values.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15484,7 +15484,7 @@
       },
       "patch": {
         "summary": "Create or update custom property values for organization repositories",
-        "description": "Create new or update existing custom property values for repositories in a batch that belong to an organization.\nEach target repository will have its custom property values updated to match the values provided in the request.\n\nA maximum of 30 repositories can be updated in a single request.\n\nUsing a value of `null` for a custom property will remove or 'unset' the property value from the repository.\n\nOnly organization owners (or users with the proper permissions granted by them) can update these properties",
+        "description": "Create new or update existing custom property values for repositories in a batch that belong to an organization.\nEach target repository will have its custom property values updated to match the values provided in the request.\n\nA maximum of 30 repositories can be updated in a single request.\n\nUsing a value of `null` for a custom property will remove or 'unset' the property value from the repository.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_values_editor` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:write` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -44564,7 +44564,7 @@
     "/repos/{owner}/{repo}/properties/values": {
       "get": {
         "summary": "Get all custom property values for a repository",
-        "description": "Gets all custom property values that are set for a repository.\nUsers with read access to the repository can use this endpoint.",
+        "description": "Gets all custom property values that are set for a repository.\nUsers with read access to the repository can use this endpoint.\n\nGitHub Apps must have the `metadata:read` repository permission to use this endpoint.",
         "tags": [
           "repos"
         ],

diff --git a/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml b/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml
@@ -10802,7 +10802,9 @@ paths:
       summary: Get all custom properties for an organization
       description: |-
         Gets all custom properties defined for an organization.
-        You must be an organization owner to use this endpoint.
+        Organization members can read these properties.
+
+        GitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/get-all-custom-properties
@@ -10836,7 +10838,12 @@ paths:
       summary: Create or update custom properties for an organization
       description: |-
         Creates new or updates existing custom properties defined for an organization in a batch.
-        Only organization owners (or users with the proper permissions granted by them) can update these properties
+
+        To use this endpoint, the authenticated user must be one of:
+          - An administrator for the organization.
+          - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.
+
+        GitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/create-or-update-custom-properties
@@ -10904,7 +10911,9 @@ paths:
       summary: Get a custom property for an organization
       description: |-
         Gets a custom property that is defined for an organization.
-        You must be an organization owner to use this endpoint.
+        Organization members can read these properties.
+
+        GitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/get-custom-property
@@ -10937,7 +10946,12 @@ paths:
       summary: Create or update a custom property for an organization
       description: |-
         Creates a new or updates an existing custom property that is defined for an organization.
-        You must be an organization owner to use this endpoint.
+
+        To use this endpoint, the authenticated user must be one of:
+        - An administrator for the organization.
+        - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.
+
+        GitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/create-or-update-custom-property
@@ -11017,7 +11031,12 @@ paths:
       summary: Remove a custom property for an organization
       description: |-
         Removes a custom property that is defined for an organization.
-        You must be an organization owner to use this endpoint.
+
+        To use this endpoint, the authenticated user must be one of:
+          - An administrator for the organization.
+          - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.
+
+        GitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/remove-custom-property
@@ -11045,6 +11064,8 @@ paths:
       description: |-
         Lists organization repositories with all of their custom property values.
         Organization members can read these properties.
+
+        GitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/list-custom-properties-values-for-repos
@@ -11101,7 +11122,11 @@ paths:
 
         Using a value of `null` for a custom property will remove or 'unset' the property value from the repository.
 
-        Only organization owners (or users with the proper permissions granted by them) can update these properties
+        To use this endpoint, the authenticated user must be one of:
+          - An administrator for the organization.
+          - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_values_editor` in the organization.
+
+        GitHub Apps must have the `organization_custom_properties:write` organization permission to use this endpoint.
       tags:
       - orgs
       operationId: orgs/create-or-update-custom-properties-values-for-repos
@@ -31886,6 +31911,8 @@ paths:
       description: |-
         Gets all custom property values that are set for a repository.
         Users with read access to the repository can use this endpoint.
+
+        GitHub Apps must have the `metadata:read` repository permission to use this endpoint.
       tags:
       - repos
       operationId: repos/get-custom-properties-values

diff --git a/descriptions-next/api.github.com/api.github.com.json b/descriptions-next/api.github.com/api.github.com.json
@@ -15058,7 +15058,7 @@
     "/orgs/{org}/properties/schema": {
       "get": {
         "summary": "Get all custom properties for an organization",
-        "description": "Gets all custom properties defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Gets all custom properties defined for an organization.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15107,7 +15107,7 @@
       },
       "patch": {
         "summary": "Create or update custom properties for an organization",
-        "description": "Creates new or updates existing custom properties defined for an organization in a batch.\nOnly organization owners (or users with the proper permissions granted by them) can update these properties",
+        "description": "Creates new or updates existing custom properties defined for an organization in a batch.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15210,7 +15210,7 @@
     "/orgs/{org}/properties/schema/{custom_property_name}": {
       "get": {
         "summary": "Get a custom property for an organization",
-        "description": "Gets a custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Gets a custom property that is defined for an organization.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15259,7 +15259,7 @@
       },
       "put": {
         "summary": "Create or update a custom property for an organization",
-        "description": "Creates a new or updates an existing custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Creates a new or updates an existing custom property that is defined for an organization.\n\nTo use this endpoint, the authenticated user must be one of:\n- An administrator for the organization.\n- A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15376,7 +15376,7 @@
       },
       "delete": {
         "summary": "Remove a custom property for an organization",
-        "description": "Removes a custom property that is defined for an organization.\nYou must be an organization owner to use this endpoint.",
+        "description": "Removes a custom property that is defined for an organization.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_definitions_manager` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:admin` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15415,7 +15415,7 @@
     "/orgs/{org}/properties/values": {
       "get": {
         "summary": "List custom property values for organization repositories",
-        "description": "Lists organization repositories with all of their custom property values.\nOrganization members can read these properties.",
+        "description": "Lists organization repositories with all of their custom property values.\nOrganization members can read these properties.\n\nGitHub Apps must have the `organization_custom_properties:read` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -15484,7 +15484,7 @@
       },
       "patch": {
         "summary": "Create or update custom property values for organization repositories",
-        "description": "Create new or update existing custom property values for repositories in a batch that belong to an organization.\nEach target repository will have its custom property values updated to match the values provided in the request.\n\nA maximum of 30 repositories can be updated in a single request.\n\nUsing a value of `null` for a custom property will remove or 'unset' the property value from the repository.\n\nOnly organization owners (or users with the proper permissions granted by them) can update these properties",
+        "description": "Create new or update existing custom property values for repositories in a batch that belong to an organization.\nEach target repository will have its custom property values updated to match the values provided in the request.\n\nA maximum of 30 repositories can be updated in a single request.\n\nUsing a value of `null` for a custom property will remove or 'unset' the property value from the repository.\n\nTo use this endpoint, the authenticated user must be one of:\n  - An administrator for the organization.\n  - A user, or a user on a team, with the fine-grained permission of `custom_properties_org_values_editor` in the organization.\n\nGitHub Apps must have the `organization_custom_properties:write` organization permission to use this endpoint.",
         "tags": [
           "orgs"
         ],
@@ -44564,7 +44564,7 @@
     "/repos/{owner}/{repo}/properties/values": {
       "get": {
         "summary": "Get all custom property values for a repository",
-        "description": "Gets all custom property values that are set for a repository.\nUsers with read access to the repository can use this endpoint.",
+        "description": "Gets all custom property values that are set for a repository.\nUsers with read access to the repository can use this endpoint.\n\nGitHub Apps must have the `metadata:read` repository permission to use this endpoint.",
         "tags": [
           "repos"
         ],