docs(socket.io): openapi schema for remaining added routes

public/openapi/write.yaml

@@ -116,6 +116,10 @@ paths:
     $ref: 'write/categories/cid/count.yaml'
   /categories/{cid}/posts:
     $ref: 'write/categories/cid/posts.yaml'
+  /categories/{cid}/children:
+    $ref: 'write/categories/cid/children.yaml'
+  /categories/{cid}/watch:
+    $ref: 'write/categories/cid/watch.yaml'
   /categories/{cid}/privileges:
     $ref: 'write/categories/cid/privileges.yaml'
   /categories/{cid}/privileges/{privilege}:

public/openapi/write/categories/cid/children.yaml

@@ -0,0 +1,36 @@
+get:
+  tags:
+    - categories
+  summary: get subcategories
+  description: |
+    This operation returns the requested category's children (aka subcategories).
+
+    It is important to note that the number of subcategories returned is dependent on the configured value for that category.
+    If a lower number is specified than there are children, then the list will be truncated to that number.
+
+    This is defined by the `subCategoriesPerPage` key in the category's hash.
+  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:
+                  categories:
+                    type: array
+                    items:
+                      $ref: ../../../components/schemas/CategoryObject.yaml#/CategoryObject

public/openapi/write/categories/cid/watch.yaml

@@ -0,0 +1,102 @@
+put:
+  tags:
+    - categories
+  summary: update watch state
+  description: |
+    This operation changes the watch state for the category.
+
+    Note that a category can be watched, not watched, or ignored:
+
+      * A category that is watched will have topics that show up in both `/unread` and `/recent`
+      * A category that is *not* watched will have topics that show up in `/recent` but not `/unread`
+      * A category that is ignored will not have topics that show up in either route.
+
+    This API call does not pertain to notifications for new topics in categories.
+    That behaviour is handled by a third-party plugin — nodebb-plugin-category-notifications
+
+    N.B. When a category's watch state is updated, all of that category's children also have their watch states updated.
+  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
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            uid:
+              type: number
+              description: This value is optional, it allows privileged uids to use this call to affect other user accounts.
+              example: 1
+            state:
+              type: string
+              enum: ['watching', 'notwatching', 'ignoring']
+              example: 'watching'
+  responses:
+    '200':
+      description: categories watch state successfully updated
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  modified:
+                    type: array
+                    description: A list of cids that have had their watch states modified.
+                    items:
+                      type: number
+delete:
+  tags:
+    - categories
+  summary: update watch state
+  description: |
+    Like the corresponding `PUT` method, this operation changes the watch state for the category.
+    However, it does not take a `state` parameter. It is assumed to be whatever the system default is (`categoryWatchState`).
+  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
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            uid:
+              type: number
+              description: This value is optional, it allows privileged uids to use this call to affect other user accounts.
+              example: 1
+  responses:
+    '200':
+      description: categories watch state successfully updated
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  modified:
+                    type: array
+                    description: A list of cids that have had their watch states modified.
+                    items:
+                      type: number

src/controllers/write/categories.js

@@ -61,6 +61,7 @@ Categories.setWatchState = async (req, res) => {
 	} else if (Object.keys(categories.watchStates).includes(state)) {
 		state = categories.watchStates[state]; // convert to integer for backend processing
 	} else {
+		console.log('throwing', cid, uid, state);
 		throw new Error('[[error:invalid-data]]');
 	}