openapi.yaml

openapi: 3.0.3
info:
  title: Similarity score api for MassBank3
  description:
    This similarity score api for MassBank3 calculates the spectral similarity
    between the spectrum defined in the query peak list and the reference spectra
    list.
  version: "0.1"
servers:
  - url: http://localhost:8080
    description: Local server
paths:
  /version:
    get:
      summary: Get the version string of the implementation.
      x-openapi-router-controller: similarity_service_impl.similarity_service_impl_controller
      operationId: version_get
      responses:
        "200":
          description: version string
          content:
            application/json:
              schema:
                type: string
              example: similarity service 0.1
  /similarity:
    post:
      summary: Create a new similarity calculation.
      x-openapi-router-controller: similarity_service_impl.similarity_service_impl_controller
      operationId: similarity_post
      requestBody:
        description: a similarity job
        required: true
        x-body-name: similarity_calculation
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/similarity_calculation"

      responses:
        "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/problem+json:
              schema:
                $ref: "#/components/schemas/error"
        "503":
          description: The server is not ready to handle the request.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: The server encountered an unexpected condition.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/error"

components:
  schemas:
    peak:
      description: a peak with m/z and intensity
      title: peak
      type: object
      properties:
        mz:
          type: number
        intensity:
          type: number
      required:
        - mz
        - intensity
      example:
        mz: 147.063
        intensity: 121.684

    peak_list:
      title: peak_list
      type: object
      properties:
        peak_list:
          type: array
          items:
            $ref: "#/components/schemas/peak"
          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
      required:
        - peak_list

    reference_spectra_list:
      description: the reference spectra list, list of ACCESSION strings
      title: reference_spectra_list
      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_fn:
      description: a supported similarity function
      title: similarity_fn
      type: object
      properties:
        similarity_fn:
          type: string
          enum:
            - cosine
          example: cosine

    similarity_calculation:
      description: a similarity calculation
      title: similarity_calculation
      allOf:
        - $ref: "#/components/schemas/peak_list"
        - $ref: "#/components/schemas/reference_spectra_list"
        - $ref: "#/components/schemas/similarity_fn"

    similarity_score:
      description: the similarity score to a reference spectrum
      title: similarity_score
      type: object
      properties:
        accession:
          type: string
        similarity_score:
          type: number
      example:
        accession: MSBNK-IPB_Halle-PB001341
        similarity_score: 0.3

    similarity_score_list:
      description: the similarity score list, result of a similarity calculation
      title: similarity_score_list
      type: object
      properties:
        similarity_score_list:
          type: array
          items:
            $ref: "#/components/schemas/similarity_score"
          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

    error:
      description: an error response
      title: error
      type: object
      properties:
        status:
          type: number
        title:
          type: string
        detail:
          type: string
        type:
          type: string
      example:
        status: 500
        title: "Database Error"
        detail: "connection failed: connection to server at \"127.0.0.1\", port 5432 failed: Connection refused\n\tIs the server running on that host and accepting TCP/IP connections?"
        type: "about:blank"