swagger.yaml

swagger: '2.0'
info:
  description: "Milla is mostly Qt Jira-specific orchestrator service for the OpenReq Qt trial that operates between Qt Jira and the OpenReq infrastructure. Milla has five main functionalities divided into three different controllers. <br>\r\n<b>Milla controller:</b><br>1) Milla fetches all or updated data from Qt Jira and stores in a caching manner the data in the Mallikas database service. <br>2) Milla orchestrates the communication to Mallikas database service so that a project, requirement etc. can be manipulated (CRUD manner) in Mallikas database service in OpenReq JSON format.<br>3) Milla orchestrates the data from Mallikas database service to Mulperi service in order to manage dependencies, carry out analyses etc. \n<br><b>Detection controller:</b><br>4) Milla calls the natural language processing services of OpenReq infrastructre that can detect from the requirements text hidden or implicit dependencies to other requirements.  <br>\r\n<b>Qt controller:</b><br>5) Milla provides the access point for the Qt Jira dependency browser in the Qt trial. <br>\r\n"
  version: '1.14'
  title: Milla
basePath: /
tags:
  - name: qt-controller
    description: Qt Controller
  - name: milla-controller
    description: Milla Controller
  - name: detection-controller
    description: Detection Controller
paths:
  /detectedFromServices:
    get:
      tags:
        - detection-controller
      summary: Get results from all detection services for the requirement id
      operationId: getDetectedFromServicesUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: requirementId
          in: query
          description: requirementId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /getConsistencyCheckForRequirement:
    get:
      tags:
        - qt-controller
      summary: Get consistency check for the transitive closure of a requirement
      description: 'First the transitive closure is created, then a consistency check is performed on it. Can now also provide custom depth value (layerCount), defaults to 5.'
      operationId: getConsistencyCheckForRequirementUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: requirementId
          in: query
          description: requirementId
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi
        - name: layerCount
          in: query
          description: layerCount
          required: false
          type: integer
          format: int32
        - name: analysisOnly
          in: query
          description: analysisOnly
          required: false
          type: boolean
        - name: timeOut
          in: query
          description: timeOut
          required: false
          type: integer
          default: 0
          format: int32
      responses:
        '200':
          description: 'Success, returns JSON model'
          schema:
            type: string
        '400':
          description: 'Failure, ex. model not found'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /getDependenciesOfRequirement:
    get:
      tags:
        - qt-controller
      summary: Get the dependencies of a requirement
      description: 'Get the dependencies of a requirement, with minimum score and max results as params'
      operationId: getDependenciesOfRequirementUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: requirementId
          in: query
          description: requirementId
          required: true
          type: string
        - name: scoreThreshold
          in: query
          description: scoreThreshold
          required: false
          type: number
          format: double
        - name: maxResults
          in: query
          description: maxResults
          required: false
          type: integer
          format: int32
      responses:
        '200':
          description: 'Success, returns JSON model'
          schema:
            type: string
        '400':
          description: 'Failure, ex. model not found'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /getJiraAuthorizationAddress:
    get:
      tags:
        - milla-controller
      summary: Get address used in authorizing Milla for Jira
      description: 'Initialize authorization process and receive Jira authorization address, where user has to log in to receive a secret key'
      operationId: jiraAuthorizationAddressUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      responses:
        '200':
          description: OK
          schema:
            type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /getTopProposedDependenciesOfRequirement:
    get:
      tags:
        - qt-controller
      summary: Detect and get top X proposed dependencies of a requirement
      description: Get the top dependencies as proposed by all detection services
      operationId: getTopProposedDependenciesUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: requirementId
          in: query
          description: requirementId
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi
        - name: maxResults
          in: query
          description: maxResults
          required: false
          type: integer
          default: 20
          format: int32
      responses:
        '200':
          description: 'Success, returns JSON model'
          schema:
            type: string
        '400':
          description: 'Failure, ex. model not found'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /getTransitiveClosureOfRequirement:
    get:
      tags:
        - qt-controller
      summary: Get the transitive closure of a requirement
      description: Returns the transitive closure of a given requirement up to the depth of 5. Can now also provide custom depth value (layerCount).
      operationId: getTransitiveClosureOfRequirementUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: requirementId
          in: query
          description: requirementId
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi
        - name: layerCount
          in: query
          description: layerCount
          required: false
          type: integer
          format: int32
      responses:
        '200':
          description: 'Success, returns JSON model'
          schema:
            type: string
        '400':
          description: 'Failure, ex. model not found'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /projectToORSI:
    post:
      tags:
        - detection-controller
      summary: Post a project to ORSI cluster computation
      operationId: postProjectToORSIUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
        - name: threshold
          in: query
          description: threshold
          required: false
          type: number
          default: 0.3
          format: double
      responses:
        '200':
          description: OK
          schema:
            type: string
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /projectToServices:
    post:
      tags:
        - detection-controller
      summary: Post a project to all detection services
      operationId: postProjectToServicesUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: string
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /qtJira:
    post:
      tags:
        - milla-controller
      summary: Import a selected project from Qt Jira and store a cache of the project in Mallikas
      description: '<b>Functionality</b>: This is the full data import from Qt Jira. A selected project including its issues are fetched from Qt Jira. The data is converted to OpenReq JSON requirements and dependencies, and OpenReq JSON project is constructed. The project, including its requirements and dependencies, is cached to Mallikas database<br><b>Postcondition</b>: The selected project is cached in Mallikas to be managed in the OpenReq infrastructure. The same project name (id) is used in Qt Jira and Mallikas.<br><b>Note:</b> For update rather than full import, see "qtJiraUpdated", which is  more efficient for large projects.</b><br><b>Parameter: </b><br>projectId: The id of the project to be fetched from Qt Jira (e.g., QTWB).'
      operationId: importFromQtJiraUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: string
        '201':
          description: 'Success, all requirements and dependencies downloaded'
          schema:
            type: string
        '400':
          description: 'Failure, ex. malformed JSON'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: 'Failure, ex. invalid URLs'
  /qtJiraUpdated:
    post:
      tags:
        - milla-controller
      summary: Import updated issues from Qt Jira to Mallikas.
      description: '<b>Functionality</b>: Import the updated Jira issues of a project from Qt Jira and send the issues as OpenReq JSON requirements and dependencies to be cached in Mallikas database<br><b>Precondition</b>: The project has been cached in Mallikas.<br><b>Postcondition</b>: New or changed Jira issues are updated to Mallikas<br><b>Exception</b>: This is not full synchronization.<br><b>Parameter: </b><br>projectId: The id of the Qt Jira project (e.g., QTWB).'
      operationId: importUpdatedFromQtJiraUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: 'Success, all updated requirements and dependencies downloaded'
          schema:
            type: string
        '201':
          description: Created
        '400':
          description: 'Failure, ex. malformed JSON'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: 'Failure, ex. invalid URLs'
  /requirementsByIds:
    post:
      tags:
        - milla-controller
      summary: Fetch a specified set of requirements in OpenReq JSON format.
      description: '<b>Functionality</b>: Fetch specified requirements and their dependencies that are cached in Mallikas database in OpenReq JSON format.<br><b>Precondition</b>: The project has been cached in Mallikas.<br><b>Postcondition</b>: An OpenReq JSON of the requirements and their dependencies is produced.<br><b>Parameter: </b><br>ids: ids as a String array, e.g. ["QTWB-1", "QTWB-2"] '
      operationId: getRequirementsByIdsUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: ids
          in: query
          description: ids
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi
      responses:
        '200':
          description: OK
          schema:
            type: object
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /requirementsByParams:
    post:
      tags:
        - milla-controller
      summary: Fetch requirements based on various parameters posted in JSON format.
      description: '<b>Functionality</b>: Fetch requirements based on various parameters given in JSON format.<br><b>Precondition</b>: The project has been cached in Mallikas.<br><b>Postcondition</b>: An OpenReq JSON of the requirements and their dependencies is produced.<br><b>Parameter: </b><br>params: RequestParams object containing various parameters to be used in database query'
      operationId: getRequirementsByParamsUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - in: body
          name: params
          description: params
          required: true
          schema:
            $ref: '#/definitions/RequestParams'
      responses:
        '200':
          description: OK
          schema:
            type: object
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /requirementsInProject:
    get:
      tags:
        - milla-controller
      summary: Fetch all requirements of a project in OpenReq JSON format.
      description: '<b>Functionality</b>: Fetch all requirements of a project including their dependencies that are cached in Mallikas database in the OpenReq JSON format.<br><b>Precondition</b>: The project has been cached in Mallikas.<br><b>Postcondition</b>: An OpenReq JSON of the project including requirements and dependencies is produced.<br><b>Parameter: </b><br>projectId: The project id in Mallikas (e.g., QTWB).<br>includeProposed: Whether to fetch proposed dependencies'
      operationId: getRequirementsInProjectUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
        - name: includeProposed
          in: query
          description: includeProposed
          required: false
          type: boolean
        - name: requirementsOnly
          in: query
          description: requirementsOnly
          required: false
          type: boolean
      responses:
        '200':
          description: OK
          schema:
            type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /sendProjectToMulperi:
    post:
      tags:
        - milla-controller
      summary: Send all requirements of the selected project to Mulperi.
      description: '<b>Functionality</b>: All requirements of a project, excluding their proposed dependencies, are fetched from Mallikas database and sent to Mulperi to construct a transitive closure. <br><b>Precondition</b>: The project, including its requirements, has been cached in Mallikas.<br><b>Postcondition</b>: Mulperi has a transitive closure of each requirement for a project up to depth five.<br><br><b>Parameter: </b><br>projectId: The project id in Mallikas (e.g., QTWB).'
      operationId: sendProjectToMulperiUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: string
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /testJiraAuthorization:
    get:
      tags:
        - milla-controller
      summary: Test if authorized for Jira
      description: 'Test if successfully authorized for Jira, returns some user statistics on success'
      operationId: testUsingGET
      consumes:
        - application/json
      produces:
        - '*/*'
      responses:
        '200':
          description: OK
          schema:
            type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /updateProject:
    post:
      tags:
        - qt-controller
      summary: Fetch whole project from Qt Jira to Mallikas and update the graph in KeljuCaas
      description: Post a Project to Mallikas database and KeljuCaas
      operationId: updateWholeProjectUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: object
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /updateProposedDependencies:
    post:
      tags:
        - qt-controller
      summary: Update proposed dependencies by user input
      description: 'Update proposed dependencies, were they accepted or rejected? If accepted, what is the type?'
      operationId: updateProposedDependenciesUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - in: body
          name: dependencies
          description: dependencies
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/Dependency'
      responses:
        '200':
          description: 'Success, returns JSON model'
          schema:
            type: string
        '201':
          description: Created
        '400':
          description: 'Failure, ex. model not found'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /updateRecentInProject:
    post:
      tags:
        - qt-controller
      summary: Fetch only the most recent issues of a project from Qt Jira to Mallikas and update the graph in KeljuCaas
      description: Post recent issues in a project to Mallikas database and KeljuCaas
      operationId: updateMostRecentIssuesInProjectUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - name: projectId
          in: query
          description: projectId
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: object
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /verifyJiraAuthorization:
    post:
      tags:
        - milla-controller
      summary: Authorize Milla for Jira with a secret key
      description: Use a secret key received from Jira to authorize Milla
      operationId: sendSecretUsingPOST
      consumes:
        - application/json
      produces:
        - '*/*'
      parameters:
        - in: body
          name: secret
          description: secret
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          schema:
            type: string
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
definitions:
  Dependency:
    type: object
    properties:
      created_at:
        type: integer
        format: int64
      dependency_score:
        type: number
        format: double
      dependency_type:
        type: string
        enum:
          - CONTRIBUTES
          - DAMAGES
          - REFINES
          - REQUIRES
          - INCOMPATIBLE
          - DECOMPOSITION
          - SIMILAR
          - DUPLICATES
          - REPLACES
      description:
        type: array
        items:
          type: string
      fromid:
        type: string
      id:
        type: string
      status:
        type: string
        enum:
          - PROPOSED
          - ACCEPTED
          - REJECTED
      toid:
        type: string
  RequestParams:
    type: object
    properties:
      created_at:
        type: string
        format: date-time
      includeProposed:
        type: boolean
      includeRejected:
        type: boolean
      maxDependencies:
        type: integer
        format: int32
      modified_at:
        type: string
        format: date-time
      projectId:
        type: string
      proposedOnly:
        type: boolean
      requirementIds:
        type: array
        items:
          type: string
      resolution:
        type: string
      scoreThreshold:
        type: number
        format: double
      status:
        type: string
      type:
        type: string