[api] Modify YAML schema so that Swagger Codegen PHP Client works

modules/api/docs/LorisRESTAPI.md

@@ -295,7 +295,7 @@ of this reference a CandidateObject. A CandidateObject is a JSON object of the f
         "Site"    : Site,
         "EDC"     : "YYYY-MM-DD",
         "DoB"     : "YYYY-MM-DD",
-        "Sex"     : "Male|Female"
+        "Sex"     : "Male|Female|Other"
 }
 ```
 
@@ -326,7 +326,7 @@ The body of the POST request should be a candidate key with a JSON object of the
         "PSCID"   : PSCID,
         "EDC"     : "YYYY-MM-DD",
         "DoB"     : "YYYY-MM-DD",
-        "Sex"     : "Male|Female",
+        "Sex"     : "Male|Female|Other",
         "Site"    : SiteName,
     }
 }
@@ -342,7 +342,7 @@ A response code of 201 Created will be returned on success, 409 Conflict if
 the PSCID already exists, 403 Forbidden when the user is creating a candidate at 
 a site other than the list of sitenames the user is affiliated with, and a 400 
 Bad Request if any data provided is invalid (PSCID format, date format, sex
-something other than Male|Female, invalid project name, invalid sitename, etc). 
+something other than Male|Female|Other, invalid project name, invalid sitename, etc). 
 A successful POST request will return a CandidateObject for the newly created 
 candidate.
 

modules/api/docs/LorisRESTAPI_v0.0.4-dev.md

@@ -295,7 +295,7 @@ of this reference a CandidateObject. A CandidateObject is a JSON object of the f
         "Site"    : Site,
         "EDC"     : "YYYY-MM-DD",
         "DoB"     : "YYYY-MM-DD",
-        "Sex"     : "Male|Female"
+        "Sex"     : "Male|Female|Other"
 }
 ```
 
@@ -326,7 +326,7 @@ The body of the POST request should be a candidate key with a JSON object of the
         "PSCID"   : PSCID,
         "EDC"     : "YYYY-MM-DD",
         "DoB"     : "YYYY-MM-DD",
-        "Sex"     : "Male|Female",
+        "Sex"     : "Male|Female|Other",
         "Site"    : SiteName,
     }
 }
@@ -342,7 +342,7 @@ A response code of 201 Created will be returned on success, 409 Conflict if
 the PSCID already exists, 403 Forbidden when the user is creating a candidate at 
 a site other than the list of sitenames the user is affiliated with, and a 400 
 Bad Request if any data provided is invalid (PSCID format, date format, sex
-something other than Male|Female, invalid project name, invalid sitename, etc). 
+something other than Male|Female|Other, invalid project name, invalid sitename, etc). 
 A successful POST request will return a CandidateObject for the newly created 
 candidate.
 
@@ -504,7 +504,7 @@ The format returned by a GET request is a JSON document of the form:
         "Candidate" : $CandID,
         "DDE" : boolean
     },
-    "$InstrumentName" : {
+    "Data" : {
         "FieldName1" : "Value1",
         "FieldName2" : "Value2",
         ...

modules/api/php/endpoints/candidate/visit/instrument/instrument.class.inc

@@ -134,14 +134,27 @@ class Instrument extends Endpoint implements \LORIS\Middleware\ETagCalculator
     /**
      * Handles a GET request
      *
+     * @param ServerRequestInterface $request The incoming PSR7 request
+     *
      * @return ResponseInterface The outgoing PSR7 response
      */
-    private function _handleGET() : ResponseInterface
+    private function _handleGET(ServerRequestInterface $request) : ResponseInterface
     {
-        $body = (new \LORIS\api\Views\Visit\Instrument(
-            $this->_visit,
-            $this->_instrument
-        ))->toArray();
+
+        $version = $request->getAttribute('LORIS-API-Version');
+        switch ($version) {
+        case 'v0.0.3':
+            $body = (new \LORIS\api\Views\Visit\Instrument(
+                $this->_visit,
+                $this->_instrument
+            ))->toArray();
+            break;
+        default:
+            $body = (new \LORIS\api\Views\Visit\Instrument_0_0_4_Dev(
+                $this->_visit,
+                $this->_instrument
+            ))->toArray();
+        }
 
         return new \LORIS\Http\Response\JsonResponse(
             $body
@@ -177,17 +190,21 @@ class Instrument extends Endpoint implements \LORIS\Middleware\ETagCalculator
         }
 
         try {
-            $instrumentname = $this->_instrument->testName;
             $this->_instrument->clearInstrument();
-            $this->_instrument->_saveValues($data[$instrumentname]);
+            $version = $request->getAttribute('LORIS-API-Version');
+            if ($version == 'v0.0.3') {
+                $instrumentname = $this->_instrument->testName;
+                $this->_instrument->_saveValues($data[$instrumentname]);
+            } else {
+                $this->_instrument->_saveValues($data['Data']);
+            }
             $this->_instrument->score();
             $this->_instrument->updateRequiredElementsCompletedFlag();
         } catch (\Throwable $e) {
             error_log($e->getMessage());
             return new \LORIS\Http\Response\JSON\InternalServerError();
         }
-        return (new \LORIS\Http\Response())
-            ->withStatus(204);
+        return (new \LORIS\Http\Response\JSON\NoContent());
     }
 
     /**
@@ -220,16 +237,20 @@ class Instrument extends Endpoint implements \LORIS\Middleware\ETagCalculator
         }
 
         try {
-            $instrumentname = $this->_instrument->testName;
-            $this->_instrument->_saveValues($data[$instrumentname]);
+            $version = $request->getAttribute('LORIS-API-Version');
+            if ($version == 'v0.0.3') {
+                $instrumentname = $this->_instrument->testName;
+                $this->_instrument->_saveValues($data[$instrumentname]);
+            } else {
+                $this->_instrument->_saveValues($data['Data']);
+            }
             $this->_instrument->score();
             $this->_instrument->updateRequiredElementsCompletedFlag();
         } catch (\Throwable $e) {
             error_log($e->getMessage());
             return new \LORIS\Http\Response\JSON\InternalServerError();
         }
-        return (new \LORIS\Http\Response())
-            ->withStatus(204);
+        return (new \LORIS\Http\Response\JSON\NoContent());
     }
 
     /**

modules/api/php/views/visit/instrument_0_0_4_dev.class.inc

@@ -0,0 +1,72 @@
+<?php declare(strict_types=1);
+/**
+ * PHP Version 7
+ *
+ * @category ApiViews
+ * @package  Loris
+ * @author   Xavier Lecours Boucher <xavier.lecours@mcin.ca>
+ * @license  http://www.gnu.org/licenses/gpl-3.0.txt GPLv3
+ * @link     https://github.com/aces/Loris/
+ */
+
+namespace LORIS\api\Views\Visit;
+
+/**
+ * Creates a representation of a visit intrument following the api response
+ * specifications.
+ *
+ * @category ApiViews
+ * @package  Loris
+ * @author   Xavier Lecours Boucher <xavier.lecours@mcin.ca>
+ * @license  http://www.gnu.org/licenses/gpl-3.0.txt GPLv3
+ * @link     https://github.com/aces/Loris/
+ */
+
+class Instrument_0_0_4_Dev
+{
+    private $_timepoint;
+    private $_instrument;
+
+    /**
+     * Constructor which sets the instance variables based on the provided timepoint
+     * and instrument.
+     *
+     * @param \Timepoint          $timepoint  The timepoint to represent
+     * @param \NDB_BVL_Instrument $instrument The instrument.
+     */
+    public function __construct(
+        \Timepoint $timepoint,
+        \NDB_BVL_Instrument $instrument
+    ) {
+        $this->_timepoint  = $timepoint;
+        $this->_instrument = $instrument;
+    }
+
+    /**
+     * Creates an serializable array of this object's data
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        $instrumentname = $this->_instrument->testName;
+        $instrumentdata = $this->_instrument->getInstanceData();
+
+        $isDDE = strpos($instrumentdata['CommentID'], 'DDE_') === 0;
+
+        $meta = [
+            'Candidate'  => $this->_timepoint->getCandID(),
+            'Visit'      => $this->_timepoint->getVisitLabel(),
+            'DDE'        => $isDDE,
+            'Instrument' => $instrumentname,
+        ];
+
+        $instrument = ['Data' => $instrumentdata];
+
+        return array_merge(
+            ['Meta' => $meta],
+            $instrument
+        );
+    }
+}
+

modules/api/static/schema-v0.0.4-dev.yml

@@ -925,7 +925,7 @@ paths:
         - Images
       summary: Get the qc values of an image
       parameters:
-        - name: candid
+        - name: id
           in: path
           description: The candidate identifier. Either PSCID or CandID.
           required: true
@@ -1288,7 +1288,7 @@ paths:
         - Dicoms
       summary: List all dicoms for that timepoint
       parameters:
-        - name: candid
+        - name: id
           in: path
           description: ID of the candidate. Either PSCID or CandID
           required: true
@@ -1852,7 +1852,9 @@ components:
       type: object
       properties:
         Candidates:
-          $ref: '#/components/schemas/Candidate'
+          type: array
+          items:
+            $ref: '#/components/schemas/Candidate'
     Candidate:
       type: object
       properties:
@@ -1873,6 +1875,7 @@ components:
           enum:
             - Female
             - Male
+            - Other
     NewCandidate:
       type: object
       properties:
@@ -1944,8 +1947,10 @@ components:
       properties:
         Meta:
           $ref: '#/components/schemas/InstrumentMeta'
-        $InstrumentShortName:
-          $ref: '#/components/schemas/InstrumentData'
+        Data:
+          type: object
+          additionalProperties:
+            type: string
     InstrumentMeta:
       type: object
       properties:
@@ -1957,10 +1962,6 @@ components:
           type: string
         DDE:
           type: boolean
-    InstrumentData:
-      type: object
-      additionalProperties:
-        type: string
     InstrumentFlags:
       type: object
       properties:
@@ -2249,6 +2250,7 @@ components:
           enum:
             - Female
             - Male
+            - Other
     InstrumentFlags_Flags:
       type: object
       properties:
@@ -2471,19 +2473,6 @@ components:
           type: string
         EventFilePath:
           type: string
-
-    VisitStage:
-      type: object
-      properties:
-        Date:
-          type: string
-        Status:
-          type: string
-          enum:
-            - Pass
-            - Failure
-            - Withdrawal
-            - In Progress
     VisitPatchFields:
       type: object
       allOf:
@@ -2492,19 +2481,6 @@ components:
           properties:
             Stages:
               $ref: '#/components/schemas/InstrumentVisit'
-
-    InstrumentVisit:
-      type: object
-      properties:
-        Visit:
-          $ref: '#/components/schemas/VisitStage'
-
-    Error:
-      type: object
-      properties:
-        error:
-          type: string
-
   securitySchemes:
     ApiKeyAuth:
       type: apiKey

modules/api/static/schema.yml

@@ -1823,7 +1823,9 @@ components:
       type: object
       properties:
         Candidates:
-          $ref: '#/components/schemas/Candidate'
+          type: array
+          items:
+            $ref: '#/components/schemas/Candidate'
     Candidate:
       type: object
       properties:
@@ -1844,6 +1846,7 @@ components:
           enum:
             - Female
             - Male
+            - Other
     NewCandidate:
       type: object
       properties:
@@ -1916,7 +1919,9 @@ components:
         Meta:
           $ref: '#/components/schemas/InstrumentMeta'
         $InstrumentShortName:
-          $ref: '#/components/schemas/InstrumentData'
+          type: object
+          additionalProperties:
+            type: string
     InstrumentMeta:
       type: object
       properties:
@@ -1928,10 +1933,6 @@ components:
           type: string
         DDE:
           type: boolean
-    InstrumentData:
-      type: object
-      additionalProperties:
-        type: string
     InstrumentFlags:
       type: object
       properties:
@@ -2220,6 +2221,7 @@ components:
           enum:
             - Female
             - Male
+            - Other
     InstrumentFlags_Flags:
       type: object
       properties: