Merge pull request #63 in VFS/oneprovider-swagger from feature/VFS-64…

…57-add-description-field-to-share-model to develop

* commit 'fb5426c20be1656b492bc181112d0b0643441256':
  VFS-6457 Improvide description of the description field in share model
  VFS-6457 Add description field to share model, fix some inconsistencies

Makefile

@@ -48,7 +48,7 @@ doc-markdown: validate
 
 preview: validate
 	$(info Open http://localhost:8088  (or http://$${DOCKER_MACHINE_IP}:8088))
-	@docker run -v `pwd`/swagger.json:/usr/share/nginx/html/swagger.json:ro -p 8088:80 ${SWAGGER_REDOC_IMAGE}
+	@docker run --rm -v `pwd`/swagger.json:/usr/share/nginx/html/swagger.json:ro -p 8088:80 ${SWAGGER_REDOC_IMAGE}
 
 bash-packages: RELEASES = $(shell git branch -a | grep "release/" | sed -n 's/.*release\/\(.*\)/\1/p')
 bash-packages:

definitions/share.yaml

@@ -7,39 +7,44 @@ properties:
   name:
     type: string
     description: The name of the share.
+  description:
+    type: string
+    description: Description of the share contents, interpreted as markdown format when displayed in GUI.
   publicUrl:
     type: string
     description: The publicly accessible URL for the share.
+  spaceId:
+    type: string
+    description: The Id of the space in which the share was created.
+  rootFileId:
+    type: string
+    description: Public Id of shared file or directory, allowing read access to its contents without authentication.
   fileType:
     type: string
     description: Denotes the type of the shared element (file or directory)
     enum:
       - file
       - dir
-  rootFileId:
-    type: string
-    description: The Id of the shared file or directory.
-  spaceId:
-    type: string
-    description: The Id of the space in which the share was created.
   handleId:
     type: string
     description: The Id of open data Handle (e.g. DOI or PID) assigned to this share or null.
 required:
   - shareId
   - name
+  - description
   - publicUrl
+  - spaceId
   - fileType
   - rootFileId
-  - spaceId
 example:
   shareId: 1f4b762b1380946e73aeca574c77f14c
-  name: MyNewShare
+  name: Experiment XYZ
+  description: '# Experiment XYZ\nThis collection contains results from Experiment XYZ.'
   publicUrl: https://onedata.org/shares/1f4b762b1380946e73aeca574c77f14c
-  fileType: dir
+  spaceId: 6ec1a5413b6f4e2b01a5c85a8fd797e2
   rootFileId: 00000000006CB663736861726547756964233339643236366165646365\
       6266666164353939663761373734313235363166342336656331613534313362366634653\
       2623031613563383561386664373937653223316634623736326231333830393436653733\
       6165636135373463373766313463
-  spaceId: 6ec1a5413b6f4e2b01a5c85a8fd797e2
+  fileType: dir
   handleId: doi:10.15911/MyShares.726855

definitions/share_create_request.yaml

@@ -4,6 +4,9 @@ properties:
   name:
     type: string
     description: The name of the share.
+  description:
+    type: string
+    description: Description of the share contents, interpreted as markdown format when displayed in GUI.
   fileId:
     type: string
     description: Id of file or directory to be shared. The whole space can also be shared.
@@ -12,4 +15,5 @@ required:
   - fileId
 example:
   name: MyShare
+  description: "# Top level header\nDescription of the share contents."
   fileId: 00000000005CF4706775696423745F772D67686431633765446F4D76546D6F2D67575F3361737A7670486B477A7936587734507265584A7723394A4F355F5F396E4C31623031594576776E667431723230677767776C6B497031394E445F6E3868677873

paths/shares/shid.yaml

@@ -21,7 +21,8 @@ get:
 
     {
       "shareId": "1f4b762b1380946e73aeca574c77f14c",
-      "name": "MyNewShare",
+      "name": "Experiment XYZ",
+      "description": "# Experiment XYZ\nThis collection contains results from Experiment XYZ.",
       "publicUrl": "https://onedata.org/shares/1f4b762b1380946e73aeca574c77f14c",
       "fileType": "dir",
       "rootFileId": "00000000006CB663736861726547756964233339643236366165646365\
@@ -73,21 +74,21 @@ patch:
     type: op_share
     id: ?BINDING(shid)
     aspect: instance
-  summary: Rename share
+  summary: Update share
   tags:
     - Share
   x-bash-codegen-description: |
-    Changes name of the share.
+    Changes name and/or description of the share.
   description: |
-    Changes name of the share.
+    Changes name and/or description of the share.
 
     ***Example cURL requests***
 
     **Changes name of the share**
     ```bash
     curl -H "X-Auth-Token: $TOKEN" -X PATCH \
     -H "Content-type: application/json" \
-    -d '{ "name": "NewShareName" }' \
+    -d '{ "name": "NewShareName", "description": "# New description" }' \
     "https://$HOST/api/v3/oneprovider/shares/$SHARE_ID"
     ```
   consumes:
@@ -117,15 +118,22 @@ patch:
       description: Share Id (e.g. '1f4b762b1380946e73aeca574c77f14c')
       type: string
       required: true
-    - name: name
+    - name: data
       in: body
-      description: New name for the share.
+      description: New share details
       schema:
-        type: string
+        type: object
+        properties:
+          name:
+            type: string
+            description: New name for the share.
+          description:
+            type: string
+            description: New description of the share.
       required: true
   x-code-samples:
     - lang: Shell
-      source: "oneprovider-rest-cli updateShare shid=$SHARE_ID name==NewShareName"
+      source: "oneprovider-rest-cli updateShare shid=$SHARE_ID name==NewShareName description==\"# New description\""
 
 
 delete: