docs: add OpenAPI examples for /api/comments

openapi.yaml

@@ -1467,6 +1467,124 @@ components:
         - computedAt
   parameters: {}
 paths:
+  /api/comments:
+    get:
+      tags:
+        - Comments
+      summary: List all comments
+      description: Root comments endpoint for listing comments securely.
+      parameters:
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            maximum: 100
+            minimum: 1
+          required: false
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          required: false
+      responses:
+        '200':
+          description: A list of comments
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  nextCursor:
+                    type: string
+                    nullable: true
+                  message:
+                    type: string
+              examples:
+                Success:
+                  summary: Example successful response
+                  value:
+                    data: []
+                    nextCursor: null
+                    message: "Comments fetched securely"
+    post:
+      tags:
+        - Comments
+      summary: Create a new comment
+      description: Creates a new comment and optionally dispatches an outbound call propagating X-Correlation-Id.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                marketId:
+                  type: string
+                body:
+                  type: string
+                  maxLength: 2000
+                authorAddress:
+                  type: string
+                outboundUrl:
+                  type: string
+                  format: uri
+              required:
+                - marketId
+                - body
+            examples:
+              CreateCommentExample:
+                summary: Example create comment request
+                value:
+                  marketId: "market-123"
+                  body: "This market has an interesting prediction."
+                  authorAddress: "GBX..."
+                  outboundUrl: "https://webhook.site/abc"
+      responses:
+        '201':
+          description: Comment created successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      marketId:
+                        type: string
+                      body:
+                        type: string
+                      authorAddress:
+                        type: string
+                        nullable: true
+                      createdAt:
+                        type: string
+                        format: date-time
+                  message:
+                    type: string
+              examples:
+                SuccessExample:
+                  summary: Example successful creation
+                  value:
+                    data:
+                      id: "c-1678886400000"
+                      marketId: "market-123"
+                      body: "This market has an interesting prediction."
+                      authorAddress: "GBX..."
+                      createdAt: "2023-03-15T12:00:00.000Z"
+                    message: "Comment created successfully"
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorBody'
   /health:
     get:
       operationId: healthCheck