Add some more responses and modify the structure of the request body

api-similarity-plugin/openapi.yaml

@@ -17,49 +17,107 @@ paths:
               schema:
                 type: string
               example: cosine similarity 1.0.0
-
   /similarity:
-    summary: Calculates the spectral similarity between the query peak list and the reference spectra list.
     post:
       summary: Create a new similarity calculation.
       requestBody:
         description: a similarity job
+        required: true
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                peak_list:
-                  type: object
-                  properties:
-                    mz:
-                      description: m/z value
-                      type: array
-                      items:
-                        type: number
-                      example: [147.063, 303.050, 449.108, 465.102, 611.161]
-                    intensity:
-                      description: intensity values
-                      type: array
-                      items:
-                        type: number
-                      example: [121.684, 10000.000, 657.368, 5884.210, 6700.000]
-                    reference_spectra_list:
-                      description: the reference spectra list, list of ACCESSION strings
-                      type: array
-                      items:
-                        type: string
-                      example: [ 'MSBNK-IPB_Halle-PB001341', 'MSBNK-IPB_Halle-PB006202',
-                                'MSBNK-IPB_Halle-PB006203', 'MSBNK-IPB_Halle-PB001342',
-                                'MSBNK-IPB_Halle-PB001343']
+              allOf:
+                - $ref: '#/components/schemas/peak_list'
+                - $ref: '#/components/schemas/reference_spectra_list'
+                - required:
+                  - peak_list
 
       responses:
-        "200":
-          description: similarity job successfully calculated
+        '200':
+          description: Similarity job successfully calculated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/similarity_score_list'
+        '400':
+          description: The server can not process the input.
+          content:
+            application/json:
+              schema:
+                type: string
+              example: 'Can not read peak list.'
+        '503':
+          description: The server is not ready to handle the request.
           content:
             application/json:
               schema:
-                description: similarity score for each reference spectrum in the order of the reference spectra list
-                type: array
-                items:
-                  type: number
+                type: string
+              example: 'Server is busy with preprocessing.'
+        '500':
+          description: The server encountered an unexpected condition.
+          content:
+            application/json:
+              schema:
+                type: string
+              example: 'some error'
+
+components:
+  schemas:
+    peak_list:
+      description: the peak list of the query spectrum
+      type: array
+      items:
+        description: a peak with m/z and intensity
+        type: object
+        properties:
+          mz:
+            description: m/z value
+            type: number
+          intensity:
+            description: intensity value
+            type: number
+      example:
+        - 'mz': 147.063
+          'intensity': 121.684
+        - 'mz': 303.050
+          'intensity': 10000.000
+        - 'mz': 449.108
+          'intensity': 657.368
+        - 'mz': 465.102
+          'intensity': 5884.210
+        - 'mz': 611.161
+          'intensity': 6700.000
+
+    reference_spectra_list:
+      description: the reference spectra list, list of ACCESSION strings
+      type: object
+      properties:
+        reference_spectra_list:
+          type: array
+          items:
+            type: string
+          example: [ 'MSBNK-IPB_Halle-PB001341', 'MSBNK-IPB_Halle-PB006202',
+                     'MSBNK-IPB_Halle-PB006203', 'MSBNK-IPB_Halle-PB001342',
+                     'MSBNK-IPB_Halle-PB001343' ]
+
+    similarity_score_list:
+      description: the similarity score list, list of similarity scores
+      type: array
+      items:
+        type: object
+        properties:
+          accession:
+            type: string
+          similarity_score:
+            type: number
+        example:
+          - 'accession': 'MSBNK-IPB_Halle-PB001341'
+            'similarity_score': 0.3
+          - 'accession': 'MSBNK-IPB_Halle-PB006202'
+            'similarity_score': 0.5
+          - 'accession': 'MSBNK-IPB_Halle-PB006203'
+            'similarity_score': 0.5
+          - 'accession': 'MSBNK-IPB_Halle-PB001342'
+            'similarity_score': 0.9
+          - 'accession': 'MSBNK-IPB_Halle-PB001343'
+            'similarity_score': 0.8