deploy: 9ecf5cb

Author: elvisdragonmao

openapi.1.0.0.yaml

@@ -529,6 +529,127 @@ paths:
             encoding:
               coverImage:
                 contentType: application/json
+  /api/forms/{formId}/highlight:
+    get:
+      operationId: Forms_getFormHighlight
+      summary: Get Form Highlight
+      description: Get the highlight question and its response statistics for a specific form. Returns 200 with questionId=null when no highlight is configured.
+      parameters:
+        - name: formId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/uuid'
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Forms.HighlightResponse'
+        '404':
+          description: The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotFound'
+      tags:
+        - Forms
+    put:
+      operationId: Forms_setFormHighlight
+      summary: Set Form Highlight
+      description: Set or update the highlight question for a specific form. Returns 400 if the question is not a choice-based type (singleChoice, multipleChoice, dropdown, detailedMultipleChoice).
+      parameters:
+        - name: formId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/uuid'
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Forms.HighlightResponse'
+        '400':
+          description: The server could not understand the request due to invalid syntax.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BadRequest'
+        '404':
+          description: The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotFound'
+      tags:
+        - Forms
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Forms.HighlightRequest'
+    patch:
+      operationId: Forms_updateFormHighlight
+      summary: Update Form Highlight
+      description: 'Partially update the configured highlight for a specific form. Currently supports updating displayTitle only. Send displayTitle: null to fall back to the question''s current title.'
+      parameters:
+        - name: formId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/uuid'
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Forms.HighlightResponse'
+        '400':
+          description: The server could not understand the request due to invalid syntax.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BadRequest'
+        '404':
+          description: The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotFound'
+      tags:
+        - Forms
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Forms.HighlightPatchRequest'
+    delete:
+      operationId: Forms_clearFormHighlight
+      summary: Clear Form Highlight
+      description: Clear the highlight question for a specific form.
+      parameters:
+        - name: formId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/uuid'
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+        '404':
+          description: The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotFound'
+      tags:
+        - Forms
   /api/forms/{formId}/publish:
     post:
       operationId: Forms_publishForm
@@ -2826,6 +2947,98 @@ components:
       description: Verification result for the given Google Sheet URL.
       examples:
         - isValid: true
+    Forms.HighlightChoice:
+      type: object
+      required:
+        - choiceId
+        - name
+        - count
+      properties:
+        choiceId:
+          allOf:
+            - $ref: '#/components/schemas/uuid'
+          description: The unique identifier of the choice.
+        name:
+          type: string
+          description: The name/text of the choice.
+        count:
+          type: integer
+          format: int32
+          description: Number of responses (draft + submitted) that selected this choice.
+      description: A choice with its response count for highlight statistics.
+      examples:
+        - choiceId: f421cfc2-2b84-4da9-9629-011af609935a
+          name: 大一
+          count: 42
+    Forms.HighlightPatchRequest:
+      type: object
+      properties:
+        displayTitle:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Custom display title for the highlight. Send null to fall back to the question's current title.
+      description: Request body for partially updating a form's highlight.
+      examples:
+        - displayTitle: Updated highlight title
+    Forms.HighlightRequest:
+      type: object
+      required:
+        - questionId
+      properties:
+        questionId:
+          allOf:
+            - $ref: '#/components/schemas/uuid'
+          description: The question ID to highlight. Must be a choice-based question (singleChoice, multipleChoice, dropdown, detailedMultipleChoice).
+        displayTitle:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Custom display title for the highlight. If omitted or null, the backend falls back to the question's current title.
+      description: Request body for setting a form's highlight question.
+      examples:
+        - questionId: ee894524-4bd8-4a64-8fd2-a53b39ca94cd
+          displayTitle: 年級分佈統計
+    Forms.HighlightResponse:
+      type: object
+      required:
+        - questionId
+        - questionTitle
+        - displayTitle
+        - choices
+      properties:
+        questionId:
+          anyOf:
+            - $ref: '#/components/schemas/uuid'
+            - type: 'null'
+          description: The highlighted question's unique identifier. Null if no highlight is configured.
+        questionTitle:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The current title of the highlighted question, fetched from the question. Null if no highlight is configured.
+        displayTitle:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The display title shown on the dashboard. Equals stored custom title if set, otherwise falls back to questionTitle. Null if no highlight is configured.
+        choices:
+          type: array
+          items:
+            $ref: '#/components/schemas/Forms.HighlightChoice'
+          description: Response counts per choice option. Empty array if no highlight is configured.
+      description: Response model for a form's highlight question statistics. When no highlight is configured, questionId is null and all other fields are null or empty.
+      examples:
+        - questionId: ee894524-4bd8-4a64-8fd2-a53b39ca94cd
+          questionTitle: 你的年級是？
+          displayTitle: 年級分佈統計
+          choices:
+            - choiceId: f421cfc2-2b84-4da9-9629-011af609935a
+              name: 大一
+              count: 42
+            - choiceId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+              name: 大二
+              count: 30
     Forms.ListSectionsResponse:
       type: object
       required:
@@ -4604,12 +4817,27 @@ components:
       type: object
       required:
         - formId
+        - totalCount
+        - draftCount
+        - submittedCount
         - responses
       properties:
         formId:
           allOf:
             - $ref: '#/components/schemas/uuid'
           description: The form ID.
+        totalCount:
+          type: integer
+          format: int32
+          description: Total number of responses for this form.
+        draftCount:
+          type: integer
+          format: int32
+          description: Number of responses in draft state.
+        submittedCount:
+          type: integer
+          format: int32
+          description: Number of submitted responses.
         responses:
           type: array
           items:
@@ -4618,6 +4846,9 @@ components:
       description: Response model for listing all responses of a form
       examples:
         - formId: 9a843aa0-8451-4e3b-b6a0-8c0e994e9040
+          totalCount: 150
+          draftCount: 30
+          submittedCount: 120
           responses: []
     Responses.OauthAnswer:
       type: object