Merge pull request #1094 from scitran/swagger-fix-undocumented-codegen

Swagger changes for code generation

swagger/Gruntfile.js

@@ -85,6 +85,16 @@ module.exports = function(grunt) {
 			}
 		},
 
+		/**
+		 * Simplify swagger for codegen
+		 */
+		simplifySwagger: {
+			core: {
+				src: 'build/swagger-ui.json',
+				dst: 'build/swagger-codegen.json'
+			}
+		},
+
 		/**
 		 * Validate swagger
 		 */
@@ -152,7 +162,8 @@ module.exports = function(grunt) {
 		'createBuildDir',
 		'flattenSwagger',
 		'schemasToDefs',
-		'validateSwagger'
+		'validateSwagger',
+		'simplifySwagger'
 	]);
 
 	/**

swagger/paths/collections.yaml

@@ -20,12 +20,13 @@ $template_arguments:
             $ref: examples/output/collection-list.json
   post:
     summary: Create a collection
-    operationId: create_collection
+    operationId: add_collection
     tags: 
     - collections
     parameters:
-      - in: body
-        name: body
+      - name: body
+        in: body
+        required: true
         schema:
           $ref: schemas/input/collection.json
     responses:
@@ -79,8 +80,9 @@ $template_arguments:
     tags: 
     - collections
     parameters:
-      - in: body
-        name: body
+      - name: body
+        in: body
+        required: true
         schema:
           $ref: schemas/input/collection-update.json
     responses:

swagger/paths/dataexplorer.yaml

@@ -6,9 +6,11 @@
       - name: simple
         in: query
         type: boolean
+        x-sdk-default: 'true'
       - name: limit
         in: query
         type: integer
+        x-sdk-default: 100
       - name: body
         in: body
         required: true

swagger/paths/groups.yaml

@@ -25,6 +25,7 @@ $template_arguments:
     parameters:
       - name: body
         in: body 
+        required: true
         schema:
           $ref: schemas/input/group-new.json
     responses:
@@ -34,6 +35,7 @@ $template_arguments:
           $ref: schemas/output/group-new.json
       '400':
         $ref: '#/responses/400:invalid-body-json'
+        
 /groups/{GroupId}:
   parameters:
     - required: true
@@ -61,6 +63,7 @@ $template_arguments:
     parameters:
       - in: body
         name: body
+        required: true
         schema:
           $ref: schemas/input/group-update.json
     responses:

swagger/paths/login.yaml

@@ -7,8 +7,7 @@
       '200':
         description: ''
         schema:
-          example:
-            success: true
+          $ref: schemas/output/login-output.json
 /logout:
   post:
     summary: Log Out
@@ -18,5 +17,4 @@
       '200':
         description: ''
         schema:
-          example:
-            auth_tokens_removed: 2
\ No newline at end of file
+          $ref: schemas/output/logout-output.json

swagger/paths/users.yaml

@@ -17,6 +17,7 @@
     parameters:
       - name: body
         in: body
+        required: true
         schema:
           $ref: schemas/input/user-new.json
     responses:
@@ -79,6 +80,7 @@
     parameters:
       - name: body
         in: body
+        required: true
         schema: 
           $ref: schemas/input/user-update.json
         description: >

swagger/schemas/definitions/acquisition.json

@@ -2,17 +2,18 @@
     "$schema": "http://json-schema.org/draft-04/schema#",
     "definitions":{
         "acquisition-input":{
-            "type": "object",
-            "properties": {
-                "public":       {"$ref":"container.json#/definitions/public"},
-                "label":        {"$ref":"common.json#/definitions/label"},
-                "info":         {"$ref":"container.json#/definitions/info"},
-                "session":      {"$ref":"common.json#/definitions/objectid"},
-                "uid":          {"$ref":"container.json#/definitions/uid"},
-                "timestamp":    {"$ref":"container.json#/definitions/timestamp"},
-                "timezone":     {"$ref":"container.json#/definitions/timezone"}
-            },
-            "additionalProperties":false
+          "type": "object",
+          "properties": {
+              "public":       {"$ref":"container.json#/definitions/public"},
+              "label":        {"$ref":"common.json#/definitions/label"},
+              "info":         {"$ref":"container.json#/definitions/info"},
+              "session":      {"$ref":"common.json#/definitions/objectid"},
+              "uid":          {"$ref":"container.json#/definitions/uid"},
+              "timestamp":    {"$ref":"container.json#/definitions/timestamp"},
+              "timezone":     {"$ref":"container.json#/definitions/timezone"}
+          },
+          "additionalProperties":false,
+          "x-sdk-model": "acquisition"
         },
         "acquisition-metadata-input": {
             "type": "object",
@@ -67,7 +68,8 @@
                   "items":{"$ref":"analysis.json#/definitions/analysis-output"}
               }
           },
-          "additionalProperties":false
+          "additionalProperties":false,
+          "x-sdk-model": "acquisition"
         }
     }
 }

swagger/schemas/definitions/analysis.json

@@ -12,7 +12,8 @@
 				"description": {"$ref":"common.json#/definitions/description"},
 				"label":       {"$ref":"common.json#/definitions/label"}
 			},
-		    "additionalProperties": false
+		    "additionalProperties": false,
+		    "x-sdk-model": "analysis-input"
 		},
 		"analysis-input-job":{
 			"type":"object",
@@ -22,7 +23,8 @@
 				"description": {"$ref":"common.json#/definitions/description"},
 				"label":       {"$ref":"common.json#/definitions/label"}
 			},
-		    "additionalProperties": false
+		    "additionalProperties": false,
+		    "x-sdk-model": "analysis-input"
 		},
 		"analysis-input-legacy":{
 			"type":"object",
@@ -41,11 +43,14 @@
 			},
 		    "additionalProperties": false
 		},
-		"analysis-input": {"anyOf": [
-			{"$ref":"#/definitions/analysis-input-adhoc"},
-			{"$ref":"#/definitions/analysis-input-job"},
-			{"$ref":"#/definitions/analysis-input-legacy"}
-		]},
+		"analysis-input-any": {
+			"anyOf": [
+				{"$ref":"#/definitions/analysis-input-adhoc"},
+				{"$ref":"#/definitions/analysis-input-job"},
+				{"$ref":"#/definitions/analysis-input-legacy"}
+			],
+			"x-sdk-schema": {"$ref":"#/definitions/analysis-input-adhoc"}
+		},
 		"analysis-update":{
 			"type":"object",
 			"properties":{
@@ -59,17 +64,20 @@
 				"_id":{"$ref":"common.json#/definitions/objectid"},
 				"inputs":{
 					"type":"array",
-					"items": {"$ref":"file.json#/definitions/file"}
+					"items": {"$ref":"file.json#/definitions/file-entry"}
 				},
 				"files":{
 					"type":"array",
-					"items": {"$ref":"file.json#/definitions/file"}
+					"items":{"$ref":"file.json#/definitions/file-entry"}
 				},
 				"job":{
 					"oneOf":[
 						{"$ref":"common.json#/definitions/objectid"},
 						{"$ref": "job.json#/definitions/job-output"}
-					]
+					],
+					"x-sdk-schema": { 
+						"$ref": "job.json#/definitions/job-output"
+					}
 				},
 				"notes":       {"$ref":"note.json#/definitions/notes-list-output"},
 				"description": {"$ref":"common.json#/definitions/description"},
@@ -77,15 +85,19 @@
 				"created":     {"$ref":"created-modified.json#/definitions/created"},
 				"modified":    {"$ref":"created-modified.json#/definitions/modified"}
 			},
-			"required":["_id", "files", "label", "created", "modified"]
+			"required":["_id", "label", "created", "modified"]
 		},
 		"analysis-list-entry":{
 			"type":"object",
 			"properties":{
 				"_id":{"$ref":"common.json#/definitions/objectid"},
+				"inputs":{
+					"type":"array",
+					"items": {"$ref":"file.json#/definitions/file-entry"}
+				},
 				"files":{
 					"type":"array",
-					"items":{"$ref":"file.json#/definitions/file"}
+					"items":{"$ref":"file.json#/definitions/file-entry"}
 				},
 				"job":         {"$ref":"common.json#/definitions/objectid"},
 				"notes":       {"$ref":"note.json#/definitions/notes-list-output"},
@@ -94,22 +106,8 @@
 				"created":     {"$ref":"created-modified.json#/definitions/created"},
 				"modified":    {"$ref":"created-modified.json#/definitions/modified"}
 			},
-			"required":["_id", "files", "label", "created", "modified"]
+			"required":["_id", "label", "created", "modified"]
 		},		
-		"analysis-job": {
-			"type": "object",
-			"properties":{
-				"analysis":{
-					"type":"object",
-					"allOf":[{"$ref":"#/definitions/analysis-input"}],
-					"required":["label"]
-				},
-				"job":{
-					"type":"object",
-					"allOf":[{"$ref":"job.json#/definitions/job-input"}]
-				}
-			}
-		},
 		"analysis-files-create-ticket-output": {
 			"type":"object",
 			"properties":{

swagger/schemas/definitions/auth.json

+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "definitions": {
+  	"login-output": {
+  		"type": "object",
+  		"properties": {
+  			"token": {"type": "string"}
+  		},
+  		"required": ["token"]
+  	},
+  	"logout-output": {
+  		"type": "object",
+  		"properties": {
+  			"tokens_removed": {"type": "integer"}
+  		},
+  		"required": ["tokens_removed"]
+  	}
+  }
+}
\ No newline at end of file

swagger/schemas/definitions/batch.json

@@ -8,7 +8,7 @@
     "batch-proposal-detail": {
       "type": "object",
       "properties": {
-        "analysis": {"$ref": "analysis.json#/definitions/analysis-input"},
+        "analysis": {"$ref": "analysis.json#/definitions/analysis-input-job"},
         "tags": {"$ref":"tag.json#/definitions/tag-list"}
       },
       "additionalProperties": false
@@ -60,7 +60,7 @@
         "gear_id": {"$ref":"job.json#/definitions/gear_id"},
         "config": {"$ref":"job.json#/definitions/config"},
         "tags": {"$ref":"tag.json#/definitions/tag-list"},
-        "analysis": {"$ref": "analysis.json#/definitions/analysis-input"},
+        "analysis": {"$ref": "analysis.json#/definitions/analysis-input-job"},
         "targets": {
           "type": "array",
           "items": {"$ref":"container.json#/definitions/container-reference"}

swagger/schemas/definitions/collection.json

 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "definitions":{
+        "collection-node": {
+            "type": "object",
+            "properties": {
+                "level": { 
+                    "type": "string", 
+                    "enum": ["project", "session", "acquisition"]
+                },
+                "_id": { "$ref": "common.json#/definitions/objectid" }
+            },
+            "additionalProperties": false
+        },
+        "collection-operation": {
+            "type": "object",
+            "properties": {
+                "operation": {
+                    "type": "string",
+                    "enum": ["add", "remove"]
+                },
+                "nodes": {
+                    "type": "array",
+                    "items": { "$ref": "#/definitions/collection-node" }
+                }
+            },
+            "additionalProperties": false
+        },
         "collection-input":{
             "type": "object",
             "properties": {
@@ -9,6 +34,7 @@
                 "info":         {"$ref": "container.json#/definitions/info"},
                 "description":  {"$ref": "common.json#/definitions/description"}
             },
+            "x-sdk-model": "collection",
             "additionalProperties": false
         },
         "collection-input-with-contents":{
@@ -18,8 +44,9 @@
                 "label":        {"$ref": "common.json#/definitions/label"},
                 "info":         {"$ref": "container.json#/definitions/info"},
                 "description":  {"$ref": "common.json#/definitions/description"},
-                "contents":     { "type": "object" }
+                "contents":     {"$ref": "#/definitions/collection-operation"}
             },
+            "x-sdk-model": "collection",
             "additionalProperties": false
         },
         "collection-new-output": {
@@ -27,7 +54,8 @@
           "properties": {
             "_id": {"$ref":"common.json#/definitions/objectid"}
           },
-          "required": ["_id"]
+          "required": ["_id"],
+          "x-sdk-return": "_id"
         },
         "collection-output":{
             "type": "object",
@@ -56,6 +84,7 @@
                     "items":{"$ref":"analysis.json#/definitions/analysis-output"}
                 }
             },
+            "x-sdk-model": "collection",
             "additionalProperties":false
         }
     }

swagger/schemas/definitions/common.json

@@ -52,7 +52,8 @@
                 "_id": {
                     "type": "string"
                 }
-            }
+            },
+            "x-sdk-return": "_id"
         }
     }
 }
\ No newline at end of file

swagger/schemas/definitions/container.json

@@ -19,7 +19,8 @@
           "properties": {
             "_id": {"$ref":"#/definitions/_id"}
           },
-          "required": ["_id"]
+          "required": ["_id"],
+          "x-sdk-return": "_id"
         },
         "container-reference": {
           "type": "object",

swagger/schemas/definitions/created-modified.json

@@ -2,10 +2,12 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "definitions":{
     "created": {
-      "type": "string"
+      "type": "string",
+      "format": "date-time"
     },
     "modified": {
-      "type": "string"
+      "type": "string",
+      "format": "date-time"
     }
   }
 }

swagger/schemas/definitions/device.json

@@ -12,6 +12,16 @@
       "type": "string",
       "enum": ["ok", "missing", "error", "unknown"]
     },
+    "device-status-entry": {
+      "type": "object",
+      "properties":{
+        "errors":    {"$ref":"#/definitions/errors"},
+        "last_seen": {"$ref":"common.json#/definitions/timestamp"},
+        "status":    {"$ref":"#/definitions/status-value"}
+      },
+      "additionalProperties":false,
+      "required": ["last_seen", "status"]      
+    },
     "device": {
       "type": "object",
       "properties": {
@@ -23,33 +33,30 @@
         "interval":  {"$ref":"#/definitions/interval"},
         "last_seen": {"$ref":"common.json#/definitions/timestamp"}
       },
+      "x-sdk-model": "device",
       "additionalProperties": false
     },
     "device-input":{
-        "type": "object",
-        "properties": {
-          "interval":       {"$ref":"#/definitions/interval"},
-          "errors":         {"$ref":"#/definitions/errors"},
-          "info":           {"$ref":"common.json#/definitions/info"}
-        },
-        "additionalProperties": false
+      "type": "object",
+      "properties": {
+        "interval":       {"$ref":"#/definitions/interval"},
+        "errors":         {"$ref":"#/definitions/errors"},
+        "info":           {"$ref":"common.json#/definitions/info"}
+      },
+      "x-sdk-model": "device",
+      "additionalProperties": false
     },
     "device-output": {
       "type": "object",
       "allOf": [{"$ref":"#/definitions/device"}],
-      "required": ["_id", "name", "method", "last_seen"]
+      "required": ["_id", "name", "method", "last_seen"],
+      "x-sdk-model": "device"
     },
     "device-status": {
       "type":"object",
       "patternProperties": {
         "^[0-9a-z.@_-]*$":{
-          "properties":{
-            "errors":    {"$ref":"#/definitions/errors"},
-            "last_seen": {"$ref":"common.json#/definitions/timestamp"},
-            "status":    {"$ref":"#/definitions/status-value"}
-          },
-          "additionalProperties":false,
-          "required": ["last_seen", "status"]
+          "$ref": "#/definitions/device-status-entry"
         }      
       }
     }

swagger/schemas/definitions/download.json

@@ -9,6 +9,7 @@
                 "-": {"$ref": "#/definitions/filter-items"},
                 "minus": {"$ref": "#/definitions/filter-items"}
             },
+            "x-sdk-ignore-properties": ["+", "-"],
             "additionalProperties": false
         },
         "filter-items": {            

swagger/schemas/definitions/file.json

@@ -41,7 +41,7 @@
           "maxLength":106
         },
         "size":{"type":"integer"},
-        "file": {
+        "file-entry": {
           "type": "object",
           "properties": {
             "name":           {"$ref":"#/definitions/name"},
@@ -63,7 +63,8 @@
             "size":        {"$ref":"#/definitions/size"},
             "info_exists": {"type": "boolean"}
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "x-sdk-model": "file-entry"
         },
         "file-input":{
             "type": "object",
@@ -76,7 +77,8 @@
               "tags":           {"$ref":"#/definitions/tags"},
               "info":           {"$ref":"common.json#/definitions/info"}
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "x-sdk-model": "file-entry"
         },
         "file-update":{
             "type": "object",
@@ -85,12 +87,14 @@
               "modality":       {"$ref":"#/definitions/modality"},
               "measurements":   {"$ref":"#/definitions/measurements"}
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "x-sdk-model": "file-entry"
         },
         "file-output":{
           "type": "object",
-          "allOf": [{"$ref":"#/definitions/file"}],
-          "required":["modified", "size"]
+          "allOf": [{"$ref":"#/definitions/file-entry"}],
+          "required":["modified", "size"],
+          "x-sdk-model": "file-entry"
         },
         "file-reference": {
           "type": "object",

swagger/schemas/definitions/gear.json

@@ -159,11 +159,11 @@
                 "url",
                 "version"
             ],
+            "x-sdk-include-empty": [ "config", "inputs" ],
             "additionalProperties": false
         },
         "gear-category": {
             "type": "string",
-            "enum": [ "utility", "analysis", "converter", "qa" ],
             "description": "The gear category"
         },
         "gear-doc": {

swagger/schemas/definitions/group.json

@@ -15,9 +15,16 @@
             "label": {"$ref": "#/definitions/label"},
             "permissions": {"$ref": "permission.json#/definitions/permission-output-list"},
             "created": {"$ref":"created-modified.json#/definitions/created"},
-            "modified": {"$ref":"created-modified.json#/definitions/modified"}
+            "modified": {"$ref":"created-modified.json#/definitions/modified"},
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           },
-          "additionalProperties":false
+          "additionalProperties":false,
+          "x-sdk-model": "group"
         },
         "group-input":{
           "type": "object",
@@ -25,7 +32,8 @@
             "_id":{"$ref":"common.json#/definitions/string-id"},
             "label": {"$ref": "#/definitions/label"}
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "x-sdk-model": "group"
         },
         "group-metadata-input": {
           "type": "object",
@@ -37,14 +45,16 @@
         "group-output":{
           "type": "object",
           "allOf": [{"$ref":"#/definitions/group"}],
-          "required": ["permissions", "created","modified","_id"]
+          "required": ["permissions", "created","modified","_id"],
+          "x-sdk-model": "group"
         },
         "group-new-output": {
           "type": "object",
           "properties": {
             "_id": {"$ref":"common.json#/definitions/string-id"}
           },
-          "required": ["_id"]
+          "required": ["_id"],
+          "x-sdk-return": "_id"
         },
         "group-output-list":{
             "type":"array",
@@ -53,7 +63,8 @@
         "project-group-output":{
           "type": "object",
           "allOf": [{"$ref":"#/definitions/group"}],
-          "required": ["_id"]
+          "required": ["_id"],
+          "x-sdk-model": "group"
         },
         "project-group-output-list":{
             "type":"array",

swagger/schemas/definitions/info.json

@@ -2,6 +2,7 @@
     "$schema": "http://json-schema.org/draft-04/schema#",
     "definitions": {
         "info-add-remove": {
+            "type": "object",
             "properties": {
                 "set":      {"type": "object", "minProperties": 1},
                 "delete":   {
@@ -16,6 +17,7 @@
             "additionalProperties": false            
         },
         "info-replace": {
+            "type": "object",
             "properties": {
                 "replace": {"type": "object"}
             },