From f279bca0382d1ee2c1189492b029fba4e4fba932 Mon Sep 17 00:00:00 2001
From: Julian Lam <julian@nodebb.org>
Date: Tue, 24 Oct 2023 13:54:19 -0400
Subject: [PATCH] docs(socket.io): added schema for new routes

---
 public/openapi/write.yaml                     |  4 +++
 public/openapi/write/categories.yaml          | 22 +++++++++++++++
 .../openapi/write/categories/cid/count.yaml   | 28 +++++++++++++++++++
 .../openapi/write/categories/cid/posts.yaml   | 28 +++++++++++++++++++
 4 files changed, 82 insertions(+)
 create mode 100644 public/openapi/write/categories/cid/count.yaml
 create mode 100644 public/openapi/write/categories/cid/posts.yaml

diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml
index b1dabb778b..e4723397b4 100644
--- a/public/openapi/write.yaml
+++ b/public/openapi/write.yaml
@@ -112,6 +112,10 @@ paths:
     $ref: 'write/categories.yaml'
   /categories/{cid}:
     $ref: 'write/categories/cid.yaml'
+  /categories/{cid}/count:
+    $ref: 'write/categories/cid/count.yaml'
+  /categories/{cid}/posts:
+    $ref: 'write/categories/cid/posts.yaml'
   /categories/{cid}/privileges:
     $ref: 'write/categories/cid/privileges.yaml'
   /categories/{cid}/privileges/{privilege}:
diff --git a/public/openapi/write/categories.yaml b/public/openapi/write/categories.yaml
index 5c26b53633..9c08994759 100644
--- a/public/openapi/write/categories.yaml
+++ b/public/openapi/write/categories.yaml
@@ -1,3 +1,25 @@
+get:
+  tags:
+    - categories
+  summary: list categories
+  description: This operation returns a flat list of categories available to the calling user
+  responses:
+    '200':
+      description: categories successfully listed
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  categories:
+                    type: array
+                    items:
+                      $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject
 post:
   tags:
     - categories
diff --git a/public/openapi/write/categories/cid/count.yaml b/public/openapi/write/categories/cid/count.yaml
new file mode 100644
index 0000000000..886152add9
--- /dev/null
+++ b/public/openapi/write/categories/cid/count.yaml
@@ -0,0 +1,28 @@
+get:
+  tags:
+    - categories
+  summary: get topic count
+  description: This operation returns the count of topics in a given category (excluding its subcategories)
+  parameters:
+    - in: path
+      name: cid
+      schema:
+        type: string
+      required: true
+      description: a valid category id, `0` for global privileges, `admin` for admin privileges
+      example: 1
+  responses:
+    '200':
+      description: categories count successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  count:
+                    type: number
\ No newline at end of file
diff --git a/public/openapi/write/categories/cid/posts.yaml b/public/openapi/write/categories/cid/posts.yaml
new file mode 100644
index 0000000000..0e46ef67a8
--- /dev/null
+++ b/public/openapi/write/categories/cid/posts.yaml
@@ -0,0 +1,28 @@
+get:
+  tags:
+    - categories
+  summary: get topic posts
+  description: This operation returns a list of posts in the category, across all topics in that category (excluding its subcategories)
+  parameters:
+    - in: path
+      name: cid
+      schema:
+        type: string
+      required: true
+      description: a valid category id, `0` for global privileges, `admin` for admin privileges
+      example: 1
+  responses:
+    '200':
+      description: categories posts successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  posts:
+                    $ref: ../../../components/schemas/PostsObject.yaml#/PostsObject
\ No newline at end of file