feat(instance): document the closeInstance endpoint (#302)

Document the closeInstance endpoint.

openapi/components/paths/instances.yaml

@@ -26,6 +26,33 @@ paths:
           $ref: ../responses/instances/InstanceResponse.yaml
         '401':
           $ref: ../responses/MissingCredentialsError.yaml
+    delete:
+      summary: Close Instance
+      tags:
+        - instances
+      operationId: closeInstance
+      security:
+        - authCookie: []
+      parameters:
+        - in: query
+          name: hardClose
+          schema:
+            type: boolean
+          required: false
+          description: Whether to hard close the instance. Defaults to false.
+      description: |-
+        Close an instance.
+
+        You can only close an instance if the ownerId is yourself or if the instance owner is a group and you have the `group-instance-moderate` permission.
+      responses:
+        '200':
+          $ref: ../responses/instances/InstanceResponse.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+        '403':
+          $ref: ../responses/instances/InstanceCloseForbiddenError.yaml
+        '404':
+          $ref: ../responses/instances/InstanceNotFoundError.yaml
   '/instances/{worldId}:{instanceId}/shortName':
     parameters:
       - $ref: ../parameters.yaml#/worldId

openapi/components/responses/instances/InstanceCloseForbiddenError.yaml

@@ -0,0 +1,16 @@
+description: Error response due to not being allowed to close an instance
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Error.yaml
+    examples:
+      Not Allowed to Close Instance Example:
+        value:
+          error:
+            message: "You're not allowed to close this instance․"
+            status_code: 403
+      Instance Already Closed Example:
+        value:
+          error:
+            message: "You're not allowed to close an already closed instance․"
+            status_code: 403

openapi/components/schemas/Instance.yaml

@@ -104,6 +104,15 @@ properties:
     type: array
     items:
       $ref: ./LimitedUser.yaml
+  nonce:
+    type: string
+  closedAt:
+    format: date-time
+    type: string
+    nullable: true
+  hardClose:
+    type: boolean
+    nullable: true
 required:
   - active
   - canRequestInvite