Skip to content

Commit

Permalink
Merge pull request #1073 from scitran/swagger-fix-undocumented
Browse files Browse the repository at this point in the history
Document missing and under-documented endpoints
  • Loading branch information
ehlertjd authored Mar 15, 2018
2 parents dbb909d + 38d9a38 commit b1edeca
Show file tree
Hide file tree
Showing 75 changed files with 1,758 additions and 231 deletions.
6 changes: 6 additions & 0 deletions api/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
37 changes: 0 additions & 37 deletions swagger/examples/gear_full.json

This file was deleted.

11 changes: 0 additions & 11 deletions swagger/examples/gears_list_just_name.json

This file was deleted.

20 changes: 0 additions & 20 deletions swagger/examples/input/job-new.json

This file was deleted.

4 changes: 2 additions & 2 deletions swagger/examples/output/analysis.json
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@
}
},
"attempt": 1,
"name": "cortex-demo",
"tags": ["ad-hoc", "cortex-demo", "analysis"],
"destination": {
"type": "analysis",
Expand Down Expand Up @@ -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"
}
35 changes: 35 additions & 0 deletions swagger/examples/output/gear-list.json
Original file line number Diff line number Diff line change
@@ -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"
}]
35 changes: 35 additions & 0 deletions swagger/examples/output/gear.json
Original file line number Diff line number Diff line change
@@ -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"
}
17 changes: 17 additions & 0 deletions swagger/examples/output/rule.json
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
34 changes: 22 additions & 12 deletions swagger/index.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
17 changes: 9 additions & 8 deletions swagger/paths/acquisitions.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down
76 changes: 76 additions & 0 deletions swagger/paths/analyses.yaml
Original file line number Diff line number Diff line change
@@ -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

Loading

0 comments on commit b1edeca

Please sign in to comment.