From 4ffe041732582d5124e8a6062b1505a080731253 Mon Sep 17 00:00:00 2001
From: Julian Lam <julian@nodebb.org>
Date: Tue, 31 Oct 2023 11:09:12 -0400
Subject: [PATCH] docs: openapi schema for api.search.categories

---
 public/openapi/write.yaml                   |  2 +
 public/openapi/write/search/categories.yaml | 96 +++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 public/openapi/write/search/categories.yaml

diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml
index 63c52430b8..1c4dfd44a4 100644
--- a/public/openapi/write.yaml
+++ b/public/openapi/write.yaml
@@ -208,6 +208,8 @@ paths:
     $ref: 'write/flags/flagId/notes.yaml'
   /flags/{flagId}/notes/{datetime}:
     $ref: 'write/flags/flagId/notes/datetime.yaml'
+  /search/categories:
+    $ref: 'write/search/categories.yaml'
   /admin/settings/{setting}:
     $ref: 'write/admin/settings/setting.yaml'
   /admin/analytics:
diff --git a/public/openapi/write/search/categories.yaml b/public/openapi/write/search/categories.yaml
new file mode 100644
index 0000000000..86d9115235
--- /dev/null
+++ b/public/openapi/write/search/categories.yaml
@@ -0,0 +1,96 @@
+get:
+  tags:
+    - search
+  summary: find categories by keyword
+  description: |
+    This operation returns a set of categories matching the keyword search.
+
+    A number of filtering options are available, and can be passed in via query string.
+  parameters:
+    - in: query
+      name: 'search'
+      schema:
+        type: string
+      required: false
+      description: The keyword used in the category search
+      example: 'announcements'
+    - in: query
+      name: 'query'
+      schema:
+        type: string
+      required: false
+      description: Likely unused — a URI-encoded JSON string containing values that are passed to `getRecentTopicReplies`.
+      example: ''
+    - in: query
+      name: 'parentCid'
+      schema:
+        type: array
+      required: false
+      description: A list of category IDs. The values received are simply reflected back in the results. Matching cids will have "selected" set to true.
+      example: '0'
+    - in: query
+      name: 'selectedCids'
+      schema:
+        type: array
+      required: false
+      description: Likely deprecated — the sorting method of topics (use `categoryTopicSort` instead.)
+      example: ''
+    - in: query
+      name: 'categoryTopicSort'
+      schema:
+        type: string
+      required: false
+      description: The sorting method of topics
+      example: 'newest_to_oldest'
+    - in: query
+      name: 'direction'
+      schema:
+        type: string
+      required: false
+      description: The sorting of returned results (if you scroll up you want the topics reversed). Set to "-1" for reversed results.
+      example: '1'
+  responses:
+    '200':
+      description: matching categories successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  categories:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        cid:
+                          type: number
+                          description: A category identifier assigned upon category creation (this value cannot be changed)
+                        name:
+                          type: string
+                          description: The category's name/title
+                        level:
+                          type: number
+                        icon:
+                          type: string
+                          description: A FontAwesome icon string
+                          example: fa-comments-o
+                        bgColor:
+                          type: string
+                          description: Theme-related, a six-character hexadecimal string representing the background colour of the category
+                        color:
+                          type: string
+                          description: Theme-related, a six-character hexadecimal string representing the foreground/text colour of the category
+                        parentCid:
+                          type: number
+                          description: The category identifier for the category that is the immediate ancestor of the current category
+                        imageClass:
+                          type: string
+                          enum: [auto, cover, contain]
+                          description: The `background-position` of the category background image, if one is set
+                        selected:
+                          type: boolean
\ No newline at end of file