Merge pull request #1073 from scitran/swagger-fix-undocumented

Document missing and under-documented endpoints

Author: ehlertjd

api/config.py

@@ -160,17 +160,23 @@ def apply_env_variables(config):
     'file.json',
     'file-list.json',
     'file-update.json',
+    'gear.json',
     'group-new.json',
     'group-update.json',
     'info_update.json',
+    'job-logs.json',
+    'job-new.json',
     'note.json',
     'packfile.json',
     'permission.json',
     'project.json',
     'project-template.json',
     'project-update.json',
+    'propose-batch.json',
+    'resolver.json',
     'rule-new.json',
     'rule-update.json',
+    'search-query.json',
     'session.json',
     'session-update.json',
     'subject.json',

swagger/examples/gear_full.json

@@ -43,7 +43,6 @@
             }
         },
         "attempt": 1,
-        "name": "cortex-demo",
         "tags": ["ad-hoc", "cortex-demo", "analysis"],
         "destination": {
             "type": "analysis",
@@ -81,7 +80,8 @@
         "created": "2016-10-18T17:45:11.816000+00:00",
         "state": "complete",
         "config": {},
-        "id": "58065fa7e5dc5b001457a882"
+        "id": "58065fa7e5dc5b001457a882",
+        "gear_id": "58065fa7e5dc5b001457a882"
     },
     "_id": "58065fa7e5dc5b001457a881"
 }

swagger/examples/gears_list_just_name.json

@@ -0,0 +1,35 @@
+[{
+    "category": "converter",
+    "gear": {
+      "inputs": {
+        "audio": {
+          "base": "file",
+          "description": "Any audio file. Plain speech suggested!"
+        }
+      },
+      "maintainer": "Nathaniel Kofalt",
+      "description": "Detects the speech content of an audio file, using the machine-learning DeepSpeech library by Mozilla.",
+      "license": "Other",
+      "author": "Nathaniel Kofalt",
+      "url": "",
+      "label": "Speech Recognition",
+      "source": "https://github.com/mozilla/DeepSpeech",
+      "version": "1",
+      "custom": {
+        "gear-builder": {
+          "image": "gear-builder-kdfqapbezk-20171219165918",
+          "container": "c15189b625a0ea450cafbb24ef0df03c26cc8cf151181976ec4289801e191032"
+        }
+      },
+      "config": {},
+      "name": "speech-recognition"
+    },
+    "created": "2017-12-20T00:09:50.381000+00:00",
+    "exchange": {
+      "git-commit": "local",
+      "rootfs-hash": "sha384:e01d925f90b097b554be0f802ef6ebb9f07000d7a6a2a0c3a25dac26893d4ac2414381e2c8e60f4b58b27c7fe8e56099",
+      "rootfs-url": "/api/gears/temp/5a39aa4e07a393001b663910"
+    },
+    "modified": "2017-12-20T00:09:50.381000+00:00",
+    "_id": "5a39aa4e07a393001b663910"
+}]

swagger/examples/input/job-new.json

@@ -0,0 +1,35 @@
+{
+    "category": "converter",
+    "gear": {
+      "inputs": {
+        "audio": {
+          "base": "file",
+          "description": "Any audio file. Plain speech suggested!"
+        }
+      },
+      "maintainer": "Nathaniel Kofalt",
+      "description": "Detects the speech content of an audio file, using the machine-learning DeepSpeech library by Mozilla.",
+      "license": "Other",
+      "author": "Nathaniel Kofalt",
+      "url": "",
+      "label": "Speech Recognition",
+      "source": "https://github.com/mozilla/DeepSpeech",
+      "version": "1",
+      "custom": {
+        "gear-builder": {
+          "image": "gear-builder-kdfqapbezk-20171219165918",
+          "container": "c15189b625a0ea450cafbb24ef0df03c26cc8cf151181976ec4289801e191032"
+        }
+      },
+      "config": {},
+      "name": "speech-recognition"
+    },
+    "created": "2017-12-20T00:09:50.381000+00:00",
+    "exchange": {
+      "git-commit": "local",
+      "rootfs-hash": "sha384:e01d925f90b097b554be0f802ef6ebb9f07000d7a6a2a0c3a25dac26893d4ac2414381e2c8e60f4b58b27c7fe8e56099",
+      "rootfs-url": "/api/gears/temp/5a39aa4e07a393001b663910"
+    },
+    "modified": "2017-12-20T00:09:50.381000+00:00",
+    "_id": "5a39aa4e07a393001b663910"
+}

swagger/examples/output/analysis.json

@@ -0,0 +1,17 @@
+{
+  "_id": "5a12f2923306be0016179f47",
+  "name": "dcm2niix",
+  "alg": "dcm2niix",
+  "any": [],
+  "all": [
+    {
+      "regex": true,
+      "type": "file.measurements",
+      "value": "^(?!non-image).+$"
+    },
+    {
+      "type": "file.type",
+      "value": "nifti"
+    }
+  ]
+}

swagger/examples/output/gear-list.json

@@ -12,36 +12,42 @@ consumes:
 - 'application/json'
 
 tags:
-  - name: files
-    description: File upload/download operations
-  - name: devices
-    description: Device operations
   - name: users
     description: User operations
-  - name: gears
-    description: Gear operations
   - name: groups
     description: Group operations
-  - name: jobs
-    description: Job operations
-  - name: collections
-    description: Collection operations
+  - name: projects
+    description: Project operations
   - name: sessions
     description: Session operations
   - name: acquisitions
     description: Acquisition operations
-  - name: projects
-    description: Project operations
+  - name: analyses
+    description: Analysis operations
+  - name: collections
+    description: Collection operations
+  - name: files
+    description: File upload/download operations
+  - name: devices
+    description: Device operations
+  - name: gears
+    description: Gear operations
+  - name: rules
+    description: Gear rule configuration
+  - name: jobs
+    description: Job operations
   - name: reports
     description: Site-wide reports
   - name: batch
     description: Batch job operations
+  - name: default
 
 paths:
   $include: 
     - paths/login.yaml
     - paths/download.yaml
     - paths/upload-by-label.yaml
+    - paths/upload-by-reaper.yaml
     - paths/upload-by-uid.yaml
     - paths/upload-match-uid.yaml
     - paths/clean-packfiles.yaml
@@ -60,6 +66,10 @@ paths:
     - paths/projects.yaml
     - paths/report.yaml
     - paths/batch.yaml
+    - paths/analyses.yaml
+    - paths/site-rules.yaml
+    - paths/dataexplorer.yaml
+    - paths/resolver.yaml
 
 
 securityDefinitions:

swagger/examples/output/gear.json

@@ -17,25 +17,22 @@ $template_arguments:
     delete-description: Read-write project permissions are required to delete an acquisition. </br>Admin project permissions are required if the acquisition contains data uploaded by sources other than users and jobs.
 
 
+/acquisitions/{AcquisitionId}/info:
+  $template: templates/container-item-info.yaml
+
 # ===== Tags =====
 /acquisitions/{AcquisitionId}/tags:
   $template: templates/tags.yaml
 /acquisitions/{AcquisitionId}/tags/{TagValue}:
   $template: templates/tags-tag.yaml
 
-# ===== Packfile =====
-/acquisitions/{AcquisitionId}/packfile-start:
-  $template: templates/packfile-start.yaml
-/acquisitions/{AcquisitionId}/packfile:
-  $template: templates/packfile.yaml
-/acquisitions/{AcquisitionId}/packfile-end:
-  $template: templates/packfile-end.yaml
-
 # ===== Files =====
 /acquisitions/{AcquisitionId}/files:
   $template: templates/file-list-upload.yaml
 /acquisitions/{AcquisitionId}/files/{FileName}:
   $template: templates/file-item.yaml
+/acquisitions/{AcquisitionId}/files/{FileName}/info:
+  $template: templates/file-item-info.yaml
 
 # ===== Notes =====
 /acquisitions/{AcquisitionId}/notes:
@@ -46,8 +43,12 @@ $template_arguments:
 # ===== Analyses =====
 /acquisitions/{AcquisitionId}/analyses:
   $template: templates/analyses-list.yaml
+  arguments:
+    allowCreate: true
 /acquisitions/{AcquisitionId}/analyses/{AnalysisId}:
   $template: templates/analysis-item.yaml
+  arguments:
+    supportsDelete: true
 /acquisitions/{AcquisitionId}/analyses/{AnalysisId}/inputs:
   $template: templates/analysis-files.yaml
   arguments:

swagger/examples/output/rule.json

@@ -0,0 +1,76 @@
+$template_arguments:
+  tag: 'analyses'
+
+/analyses/{AnalysisId}:
+  $template: templates/analysis-item.yaml
+  arguments:
+    supportsDelete: false
+
+/analyses/{AnalysisId}/inputs:
+  $template: templates/analysis-files.yaml
+  arguments:
+    filegroup: inputs
+
+/analyses/{AnalysisId}/inputs/{Filename}:
+  $template: templates/analysis-files-create-ticket-filename.yaml
+  arguments:
+    filegroup: inputs
+
+/analyses/{AnalysisId}/files:
+  $template: templates/analysis-files.yaml
+  arguments:
+    filegroup: outputs
+
+/analyses/{AnalysisId}/files/{Filename}:
+  $template: templates/analysis-files-create-ticket-filename.yaml
+  arguments:
+    filegroup: outputs
+  
+/{ContainerName}/{ContainerId}/{SubcontainerName}/analyses:
+  parameters:
+    - name: ContainerName
+      in: path
+      type: string
+      required: true
+      enum:
+        - groups
+        - projects
+        - sessions
+        - acquisitions
+        - collections
+      description: The parent container type
+    - name: ContainerId
+      in: path
+      type: string
+      required: true
+      description: The parent container id
+    - name: SubcontainerName
+      in: path
+      type: string
+      required: true
+      enum:
+        - all
+        - projects
+        - sessions
+        - acquisitions
+      description: The sub container type
+  get:
+    summary: Get nested analyses for a container
+    description: >
+      Returns analyses that belong to containers of the specified type that belong
+      to ContainerId. 
+
+      For example: `projects/{ProjectId}/acquisitions/analyses` will return any analyses 
+      that have an acquisition that is under that project as a parent.
+
+      The `all` keyword is also supported, for example: projects/{ProjectId}/all/analyses 
+      will return any analyses that have any session or acquisition or the project itself as a parent.
+    operationId: get_analyses
+    tags:
+    - analyses
+    responses:
+      '200': 
+        description: The list of analyses
+        schema:
+          $ref: schemas/output/analyses-list.json  
+