From 70652ad4804f035b7ea17041b90595dadf37a769 Mon Sep 17 00:00:00 2001
From: Julian Lam <julian@nodebb.org>
Date: Mon, 22 Aug 2022 16:28:09 -0400
Subject: [PATCH] docs(openapi): v3 spec for new user export routes

---
 public/openapi/write.yaml                     |  2 +
 .../openapi/write/users/uid/exports/type.yaml | 85 +++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 public/openapi/write/users/uid/exports/type.yaml

diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml
index eb74cef2d9..6f55dbcfc0 100644
--- a/public/openapi/write.yaml
+++ b/public/openapi/write.yaml
@@ -86,6 +86,8 @@ paths:
     $ref: 'write/users/uid/emails/email.yaml'
   /users/{uid}/emails/{email}/confirm:
     $ref: 'write/users/uid/emails/email/confirm.yaml'
+  /users/{uid}/exports/{type}:
+    $ref: 'write/users/uid/exports/type.yaml'
   /groups/:
     $ref: 'write/groups.yaml'
   /groups/{slug}:
diff --git a/public/openapi/write/users/uid/exports/type.yaml b/public/openapi/write/users/uid/exports/type.yaml
new file mode 100644
index 0000000000..928cb9b8f4
--- /dev/null
+++ b/public/openapi/write/users/uid/exports/type.yaml
@@ -0,0 +1,85 @@
+head:
+  tags:
+    - users
+  summary: Check if a user's export exists
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to make the query for
+      example: 1
+    - in: path
+      name: type
+      schema:
+        type: string
+      required: true
+      description: The type of export to query
+      example: posts
+  responses:
+    '204':
+      description: Exported file found.
+    '404':
+      description: Exported file not found — this could be because an export has never been generated for this user.
+get:
+  tags:
+    - users
+  summary: Download a user's exported data
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to make the query for
+      example: 1
+    - in: path
+      name: type
+      schema:
+        type: string
+      required: true
+      description: The type of export to download
+      example: posts
+  responses:
+    '200':
+      description: A download containing the requested exported data
+    '404':
+      description: Exported file not found — this could be because an export has never been generated for this user.
+post:
+  tags:
+    - users
+  summary: Generate a user export
+  description: |
+    This operation generates a user export file for later download.
+    It will return immediately with the `202 Accepted` response code, meaning the request was accepted for processing.
+    The expected behaviour is for the client to then poll the corresponding `HEAD` method until it returns a `204 No Content`
+    (or if awaiting a new export, for the `Last-Modified` or `ETag` header to change)
+    at which point the `GET` method can be called for download.
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to make the query for
+      example: 1
+    - in: path
+      name: type
+      schema:
+        type: string
+      required: true
+      description: The type of export to download
+      example: posts
+  responses:
+    '202':
+      description: Successfully started generating the requested user export
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
\ No newline at end of file