diff --git a/public/openapi/read.yaml b/public/openapi/read.yaml
index 6b60ed159b..eb798b08d7 100644
--- a/public/openapi/read.yaml
+++ b/public/openapi/read.yaml
@@ -9669,12 +9669,20 @@ paths:
       tags:
         - tags
       summary: /api/tags/{tag}
+      description: Returns a list of topics that are tagged with {tag}
       parameters:
         - name: tag
+          description: The tag used to retrieve the topics
           in: path
           required: true
           schema:
             type: string
+        - name: page
+          description: Page number used in pagination
+          in: query
+          required: false
+          schema:
+            type: number
       responses:
         "200":
           description: ""
@@ -9685,6 +9693,7 @@ paths:
                 properties:
                   topics:
                     type: array
+                    description: An array of topics that are all tagged with {tag}
                     items:
                       type: object
                       properties:
@@ -10039,13 +10048,12 @@ paths:
                           properties:
                             html:
                               type: string
-        "304":
-          description: ""
   /api/tags:
     get:
       tags:
         - tags
       summary: /api/tags
+      description: Returns a list of tags with the most topics
       responses:
         "200":
           description: ""
@@ -10056,15 +10064,19 @@ paths:
                 properties:
                   tags:
                     type: array
+                    description: An array of tags with the most topics
                     items:
                       type: object
                       properties:
                         value:
                           type: string
+                          description: The raw tag
                         score:
                           type: number
+                          description: Number of topics tagged by this tag
                         valueEscaped:
                           type: string
+                          description: This is the escaped tag value, equal to validator.escape(value)
                         color:
                           type: string
                         bgColor: