Checkpoint in swagger doc conversion. Users and groups done.

raml/schemas/definitions/avatars.json

 {
   "$schema": "http://json-schema.org/draft-04/schema#",
-  "title": "Group",
+  "title": "Avatar",
   "type": "object",
   "properties": {
     "gravatar":         {"type": ["string", "null"], "format": "uri" },

raml/schemas/input/device.json

 {
   "$schema": "http://json-schema.org/draft-04/schema#",
-  "allOf":[{"$ref":"../definitions/device.json#/definitions/device-input"}]
+  "allOf":[{"$ref":"../definitions/device.json#/definitions/device-input"}],
+  "example": {
+  	"$ref": "../../examples/input/device.json"
+  }
 }

raml/schemas/input/download.json

@@ -21,6 +21,9 @@
     },
     "title": "Download",
     "type": "object",
+    "example": {
+        "$ref": "../../examples/create_download_incomplete_and_dicom.json"
+    },
     "properties": {
         "optional": {
             "type": "boolean"

raml/schemas/input/group-new.json

@@ -3,5 +3,8 @@
   "allOf":[
     {"$ref":"../definitions/group.json#/definitions/group-input"}
   ],
-  "required": ["_id"]
+  "required": ["_id"],
+  "example": {
+  	"$ref": "../../examples/input/group-new.json"
+  }
 }

raml/schemas/input/group-update.json

 {
     "$schema": "http://json-schema.org/draft-04/schema#",
-    "allOf":[{"$ref":"../definitions/group.json#/definitions/group-input"}]
+    "allOf":[{"$ref":"../definitions/group.json#/definitions/group-input"}],
+    "example": {
+    	"$ref": "../../examples/input/group-update.json"
+    }
 }

raml/schemas/input/permission.json

@@ -3,5 +3,8 @@
   "type": "object",
   "allOf":[{"$ref":"../definitions/permission.json#/definitions/permission"}],
   "key_fields": ["_id"],
-  "required": ["_id", "access"]
+  "required": ["_id", "access"],
+  "example": {
+  	"$ref": "../../examples/input/permission.json"
+  }
 }

raml/schemas/input/tag.json

 {
   "$schema": "http://json-schema.org/draft-04/schema#",
-  "allOf":[{"$ref":"../definitions/tag.json#/definitions/tag"}]
+  "allOf":[{"$ref":"../definitions/tag.json#/definitions/tag"}],
+  "example": {
+  	"$ref": "../../examples/input/tag.json"
+  }
 }

raml/schemas/input/user-new.json

@@ -2,5 +2,8 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "allOf":[{"$ref":"../definitions/user.json#/definitions/user-input"}],
-  "required":["_id", "firstname", "lastname"]
+  "required":["_id", "firstname", "lastname"],
+  "example": {
+    "$ref": "../../examples/input/user-new.json"
+  }
 }

raml/schemas/input/user-update.json

@@ -4,5 +4,8 @@
   "type": "object",
   "allOf":[
     {"$ref":"../definitions/user.json#/definitions/user-input"}
-  ]
+  ],
+  "example": {
+  	"$ref": "../../examples/input/user-update.json"
+  }
 }

raml/schemas/output/user-list.json

@@ -9,5 +9,8 @@
        "_id", "firstname", "lastname",
        "root", "email", "created", "modified"
     ]
+  },
+  "example": {
+    "$ref": "../../examples/user-list.json"
   }
 }

raml/schemas/output/user-new.json

@@ -8,5 +8,8 @@
   },
   "required": [
     "_id"
-  ]
+  ],
+  "example": {
+    "$ref": "../../examples/output/user-new.json"
+  }
 }

swagger/Gruntfile.js

@@ -23,6 +23,12 @@ module.exports = function(grunt) {
 						cwd: '../raml/schemas', 
 						src: ['**'], 
 						dest: 'build/schemas' 
+					},
+					{
+						expand: true,
+						cwd: '../raml/examples',
+						src: ['**'],
+						dest: 'build/examples'
 					}
 				]
 			},
@@ -125,6 +131,7 @@ module.exports = function(grunt) {
 
 	/**
 	 * Build swagger-ui
+	 * TODO: Put the distributed version of swagger-ui in the ../docs folder
 	 */
 	grunt.registerTask('build-ui', [
 		'build-schema',

swagger/common/tags.yaml

+add-tag-parameters:
+  - name: body
+    in: body
+    schema:
+      $ref: schemas/input/tag.json
+
+modify-tag-parameters:
+  - name: body
+    in: body
+    schema:
+      $ref: schemas/input/tag.json
+
+modify-tag-responses:
+  '200':
+    $ref: '#/responses/200:modified-with-count'
+  '400':
+    $ref: '#/responses/400:invalid-body-json'
+
+delete-tag-responses:
+  '200':
+    $ref: '#/responses/200:modified-with-count'
+
+get-tag-responses:
+  '200':
+    description: Returns a single tag by name
+    schema:
+      $ref: schemas/output/tag.json
+    examples:
+      response:
+        $ref: examples/output/tag.json
+

swagger/index.yaml

@@ -2,17 +2,62 @@ swagger: '2.0'
 info:
   version: 0.0.1
   title: SciTran
+host: 'dev.flywheel.io'
 basePath: '/api'
 schemes: 
-- 'api'
+- 'https'
 produces:
 - 'application/json'
 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
+
 paths:
   $ref: ./paths/index.yaml
-definitions:
+# definitions:
   #  $ref: ./definitions/index.yaml
 
+securityDefinitions:
+  ApiKey:
+    type: apiKey
+    in: header
+    name: Authorization
+    description: |
+      Your API key is available on your Profile page from within the Flywheel Application.
+      **NOTE:** The API key should be prefixed with `scitran-user` if you're testing APIs on this page.
+      
+      e.g. `scitran-user dev.flywheel.io:DFCAds356sdvd`.
 
+security: 
+  - ApiKey: []
 
+responses:
+  $ref: ./responses/index.yaml
+
+definitions:
+  filterDefinition:
+    type: object
+    additionalProperties: false
+    properties:
+      +:
+        $ref: '#/definitions/filterItems'
+      '-':
+        $ref: '#/definitions/filterItems'
+  filterItems:
+    minItems: 1
+    type: array
+    items:
+      type: string
\ No newline at end of file

swagger/paths/clean-packfiles.yaml

+clean-packfiles:
+  post:
+    summary: Clean up expired upload tokens and invalid token directories.
+    operationId: clean_packfiles
+    responses:
+      '200':
+        description: 'Expired and invalid tokens have been cleaned'
+        schema:
+          example:
+            tokens: 5
+            directories: 3
\ No newline at end of file

swagger/paths/config-js.yaml

+config-js:
+  get:
+    summary: Return public Scitran configuration information in javascript format.
+    operationId: get_config_js
+    produces:
+      - text/html
+    responses:
+      '200':
+        description: ''
+        schema:
+          example: |
+            config = {
+                  "auth": {
+                      "auth_endpoint": "https://accounts.google.com/o/oauth2/auth",
+                      "client_id": "949263322061-6q4fqi0m4ihkp1v5n6v8q9bef4gd0f1k.apps.googleusercontent.com",
+                      "id_endpoint": "https://www.googleapis.com/plus/v1/people/me/openIdConnect",
+                      "verify_endpoint": "https://www.googleapis.com/oauth2/v1/tokeninfo"
+                  },
+                  "created": "2016-03-31T16:30:00.852000+00:00",
+                  "modified": "2016-03-31T16:30:00.852000+00:00",
+                  "site": {
+                      "api_url": "https://10.240.0.2:443/api",
+                      "central_url": "https://sdmc.scitran.io/api",
+                      "id": "local",
+                      "name": "BaliDemo",
+                      "registered": false,
+                      "ssl_cert": null
+                  } 

swagger/paths/config.yaml

+config:
+  get:
+    summary: Return public Scitran configuration information
+    operationId: get_config
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/config.json
+        examples:
+          response:
+            $ref: examples/scitran_config.json

swagger/paths/devices.yaml

+devices:
+  get:
+    summary: List all devices.
+    description: Requires login.
+    operationId: get_all_devices
+    tags:
+    - devices
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/device-list.json
+        examples:
+          response:
+            $ref: examples/output/device-list.json
+  post:
+    summary: Modify a device's interval, info or set errors.
+    description: |
+      Will modify the device record of device making the request.
+      Request must be drone request.
+    operationId: update_device
+    tags:
+    - devices
+    responses:
+      '200':
+        description: ''
+        schema:
+          example:
+            modified: '1'
+    parameters:
+      - name: body
+        in: body
+        schema:
+          $ref: schemas/input/device.json
+devices-self:
+  get:
+    summary: Get device document for device making the request.
+    description: Request must be a drone request.
+    operationId: get_current_device
+    tags:
+    - devices
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/device.json
+        examples:
+          response:
+              $ref: examples/output/device.json
+devices-status:
+  get:
+    summary: Get status for all known devices.
+    description: ok - missing - error - unknown
+    operationId: get_all_devices_status
+    tags:
+    - devices
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/device-status.json
+        examples:
+          response:
+            $ref: examples/output/device-status.json
+devices-device:
+  parameters:
+    - required: true
+      type: string
+      in: path
+      name: DeviceId
+  get:
+    summary: Get device details
+    operationId: get_device
+    tags:
+    - devices
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/device.json
+        examples:
+          response:
+            $ref: examples/output/device.json
+      '404':
+        description: DeviceId not found

swagger/paths/download.yaml

+download:
+  post:
+    summary: Create a download ticket
+    description: |
+      Use filters in the payload to exclude/include files.
+      To pass a single filter, each of its conditions should be satisfied.
+      If a file pass at least one filter, it is included in the targets.
+    operationId: create_download_ticket
+    tags:
+    - files
+    responses:
+      '200':
+        description: ''
+        schema:
+          example:
+            ticket: 579e97738120be2ada087feb
+            file_cnt: 3
+            size: 64523904
+    parameters:
+      - name: prefix
+        in: query
+        description: |
+          A string to customize the name of the download
+          in the format <prefix>_<timestamp>.tar.gz.
+          Defaults to "scitran".
+        type: string                
+      - name: body
+        in: body
+        schema:
+          $ref: schemas/input/download.json
+        description: Download files with tag 'incomplete' OR type 'dicom'
+  get:
+    summary: Download files listed in the given ticket.
+    description: |
+      You can use POST to create a download ticket
+      The files listed in the ticket are put into a tar archive,
+      which is then compressed with gzip (.tar.gz)
+    operationId: download_ticket
+    tags:
+    - files
+    parameters:
+      - required: true
+        description: ID of the download ticket
+        type: string
+        in: query
+        name: ticket
+    produces:
+      - application/octet-stream
+    responses:
+      '200':
+        description: The requested tarball download as a binary stream
+      '400':
+        description: Ticket not for this source IP
+      '404':
+        description: No such ticket

swagger/paths/engine.yaml

+engine:
+  post:
+    summary: Upload a list of file fields.
+    description: |
+      ### Default behavior:
+       >Uploads a list of file fields sent as file1, file2, etc to an existing
+        container and updates fields of the files, the container and it's
+        parents as specified in the metadata fileformfield using the
+        engine placer class
+
+      ### When ``level`` is ``analysis``:
+      > Uploads a list of files to an existing analysis object, marking
+        all files as ``output=true`` using the job-based analyses placer
+        class.  See schemas/input/analysis.json
+    operationId: engine_upload
+    responses:
+      '200':
+        description: A list of FileInfo objects
+        schema:
+          example:
+            $ref: examples/file_info_list.json
+    parameters:
+      - in: body
+        name: body
+        description: >
+          Object encoded as a JSON string.
+
+          By default JSON must match the specified enginemetadata.json schema
+
+          If ``level`` is ``analysis``, JSON must match AnalysisUploadMetadata schema
+        schema:
+          $ref: schemas/input/enginemetadata.json
+      - required: true
+        description: Which level to store files in
+        enum:
+          - project
+          - session
+          - acquisition
+          - analysis
+        type: string
+        in: query
+        name: level
+      - required: true
+        description: The ID of the container to place files in
+        type: string
+        in: query
+        name: id
+      - description: Required if ``level`` is ``analysis``
+        type: string
+        in: query
+        name: job
+        required: true
\ No newline at end of file