Merge pull request #244 from hubmapconsortium/shirey/update-docs

updated docs

Author: DerekFurstPitt

entity-api-spec.yaml

@@ -1440,9 +1440,23 @@ paths:
           required: false
           schema:
             type: string
+            enum: ['true', 'false']
       responses:
         '200':
-          description: The revision number (integer) on successful operation
+          description: The list of revised datasets that the referenced dataset is a member of including the index number of the revision, where 1 is the oldest version of any revision chain
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  dataset_uuid:
+                    type: string
+                    description: The uuid of a dataset
+                  revision_number:
+                    type: integer
+                    description: The number in the revision chain of this dataset where 1 is the oldest revision
+                  dataset:
+                    $ref: '#/components/schemas/Dataset'
         '400':
           description: Invalid or misformatted entity identifier, or the given entity is not a Dataset
         '401':
@@ -1455,29 +1469,34 @@ paths:
           description: Internal error
   '/datasets/{id}/retract':
     put:
-      summary: 'Takes a json with a single required field {retraction_reason: string}. The dataset for the given id is modified to include this new retraction_reason field and sets the property sub_status to retracted. The complete modified dataset is returned. This will not work for anything besides published datasets. If the user has no token or has a token without membership in HuBMAP-Data-Admin group, then a 403 response should be returned.'
+      summary: 'Retracts a dataset after it has been published. Requires a json body with a single field {retraction_reason: string}. The dataset for the given id is modified to include this new retraction_reason field and sets the dataset property sub_status to Retracted. The complete modified dataset is returned. Requires that the dataset being retracted has already been published (dataset.status == Published. Requires a user token with membership in the HuBMAP-Data-Admin group otherwise then a 403 will be returned.'
       parameters:
         - name: id
-        in: path
-        description: The unique identifier of entity. This identifier can be either a HubMAP ID (e.g. HBM123.ABCD.456) or UUID
-        required: true
-        schema:
-          type: string
+          in: path
+          description: The unique identifier of entity. This identifier can be either a HubMAP ID (e.g. HBM123.ABCD.456) or UUID
+          required: true
+          schema:
+            type: string
       requestBody:
+        description: A json body with a single, required retraction_reason parameter contianing the reason why the dataset is being retracted.
         content:
           application/json:
             schema:
-              retraction_reason: string
+              type: object
+              properties:
+                retraction_reason:
+                  type: string
+                  description: Free text describing why the dataset was retracted 
       responses:
         '200':
           description: The complete dataset with modified sub_status and retraction_reason
         '400':
-          description: Invalid or misformatted entity identifier, or the given entity is not a Dataset or is not published
+          description: Invalid or misformatted entity identifier, the given entity is not a Dataset, is not published or the required retraction_reason was not included in a json body
         '401':
           description: The user's token has expired or the user did not supply a valid token
         '403':
-          description: The user is not authorized to query the retract the given dataset.
+          description: The user is not authorized to query the retract the given dataset.  The user must be a member of the HuBMAP-Data-Admin group
         '404':
           description: The target dataset could not be found
         '500':
-          description: Internal error
+          description: Internal error