deposits: add docs for upload action

Signed-off-by: Parth Shandilya <parth.shandilya@cern.ch>

Author: Parth Shandilya

spec/components/schemas/UploadRepositories.yaml

@@ -0,0 +1,39 @@
+description: Upload Resource
+type: object
+oneOf:
+  - title: Create Repository as user and attach to deposit
+    type: object
+    properties:
+      webhook:
+        type: string
+        enum:
+          - repo_create
+      url:
+        type: string
+        description: The git url that can point to a repository or specific file.
+    required:
+      - url
+      - webhook
+  - title: Attach Repository to deposit
+    properties:
+      webhook:
+        type: string
+        enum:
+          - None
+          - repo_download_attach
+      url:
+        type: string
+        description: The git url that can point to a repository or specific file.
+    required:
+      - url
+      - webhook
+  - title: Create Repository from Schema configuration and attach to depoit
+    type: object
+    properties:
+      webhook:
+        type: string
+        enum:
+          - repo_create_default
+    required:
+      - url
+      - webhook

spec/paths/deposits@{depid}@actions@upload.yaml

@@ -6,37 +6,44 @@ parameters:
       type: string
       format: uuid
     required: true
-  - name: type
-    in: query
-    description: Url type (repo/url)
-    schema:
-      type: string
-      enum: [url, repo]
-    required: true
-  - name: url
-    in: query
-    description: Url of repo/file to upload
-    schema:
-      type: string
-      format: uuid
-    required: true
 post:
   tags:
     - Deposits
-  summary: Upload files/data
-  description: |
-    Upload files/data to your analysis, in a specified deposit record.
-    The following type of uploads are possible:
-      * Local files
-      * Git repos
-      * URL linked files
+  summary: Upload action for repositories
+  description: >-
+
+    - **Download** a snapshot of repository, that you'd like to preserve with your analysis.
+      You can point to the whole repo, specific branch or even a single file whatever your analysis needs.
+      Some repositories are private or restricted for CERN users only (like all the repos in CERN Gitlab) - 
+      to download those you need to connect your Github/Gitlab account first.
+
+    - **Connect** repositories with analysis that are still in progress, to keep them in sync.
+      We'll make a new snapshot on any changes pushed in this repository.
+      This way your analysis will be always up to date with your code. 
+      Keep in mind that you cannot connect to public repositories (owner has to give you a specific access to do that).
+      Upload files/data to your analysis, in a specified deposit record.
 
-    The API differentiates between whole repos (saved as .tar) and single files
-    from repos, so the parameter "type" is necessary.
-  operationId: uploadDeposit
+  operationId: connectToDeposit
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UploadRepositories'
+        examples:
+          Create Repository as user and attach to deposit:
+            value:
+              url: https://github.com/cernanalysispreservation/cap-api-docs
+              webhook: repo_create
+          Attach Repository to deposit:
+            value:
+              url: https://github.com/cernanalysispreservation/cap-api-docs/README.md
+              webhook: repo_download_attach
+          Create Repository from Schema configuration and attach to depoit:
+            value:
+              webhook: repo_create_default
   responses:
-    '200':
-      description: OK
+    '201':
+      description: Created
       headers:
         X-Rate-Limit:
           description: calls per hour allowed by the user