Merge pull request #5426 from hypothesis/patch-group-api-docs

Add API docs for `PATCH /api/groups/{id}`

docs/_extra/api-reference/hypothesis.yaml

@@ -371,6 +371,44 @@ paths:
       security:
         - authClientForwardedUser: []
         - developerAPIKey: []
+
+  /groups/{id}:
+    patch:
+      tags:
+        - groups
+      summary: Update a  group
+      operationId: patchGroup
+      description: >
+        Update an existing group. The authenticated user must be the group's original creator to have permission to update it.
+      parameters:
+        - name: id
+          in: path
+          description: The group's `id` or `groupid`
+          required: true
+          type: string
+        - name: group
+          in: body
+          description: Group properties to update
+          required: true
+          schema:
+            $ref: '#/definitions/UpdateGroup'
+      responses:
+        '200':
+          description: Group successfully updated
+          schema:
+            $ref: '#/definitions/GroupResult'
+        '400':
+          description: Could not update group from your request
+          schema:
+            $ref: '#/definitions/Error'
+        '409':
+          description: Conflict
+          schema:
+            $ref: '#/definitions/ConflictError'
+      security:
+        - authClientForwardedUser: []
+        - developerAPIKey: []
+
   /search:
     get:
       tags:
@@ -681,6 +719,8 @@ definitions:
         type: integer
   NewGroup:
     $ref: './schemas/new-group.yaml#/Group'
+  UpdateGroup:
+    $ref: './schemas/update-group.yaml#/Group'
   GroupResult:
     $ref: './schemas/group.yaml#/Group'
   GroupResults:

docs/_extra/api-reference/schemas/update-group.yaml

@@ -0,0 +1,22 @@
+Group:
+  type: object
+  properties:
+    name:
+      type: string
+      description: The name of the group
+      minLength: 3
+      maxLength: 25
+    description:
+      type: string
+      description: group description
+      maxLength: 250
+    groupid:
+      type: string
+      pattern: "group:[a-zA-Z0-9._\\-+!~*()']{1,1024}@.*$"
+      description: >
+        <p><mark>NEW/EXPERIMENTAL</mark></p>
+        <p>For AuthClient-authenticated requests only.</p>
+
+        <p>Optional unique identifier for this group, in the format `"group:<unique_identifier>@<authority>"`, e.g.: `"group:my-own-unique-id-123@myauthority.com"`. The `authority` value must match the requesting client's authorized authority. </p>
+
+        <p>This property is intended to allow third-party authorized clients to set their own unique identifier for a group. As such, the value of the `unique_identifier` string must be unique within the `authority`. A uniqueness violation will result in an `HTTP 409: Conflict` response.</p>