From c50976c701deacc0adc1f8c7893edbcdfea024b2 Mon Sep 17 00:00:00 2001 From: Travis CI User Date: Wed, 28 Mar 2018 20:58:36 +0000 Subject: [PATCH] OpenAPI changed --- src/main/resources/swagger/openapi.yaml | 102 +++++++++++++----------- 1 file changed, 57 insertions(+), 45 deletions(-) diff --git a/src/main/resources/swagger/openapi.yaml b/src/main/resources/swagger/openapi.yaml index 0ee0acf9..c801a406 100644 --- a/src/main/resources/swagger/openapi.yaml +++ b/src/main/resources/swagger/openapi.yaml @@ -4,16 +4,16 @@ info: description: >- Proposed API for GA4GH (Global Alliance for Genomics & Health) tool repositories. A tool consists of a set of container images that are paired - with a set of documents (examples include CWL (Common Workflow Language) or - WDL (Workflow Description Language) or NFL (Nextflow)) that describe how to - use those images and a set of specifications for those images (examples are - Dockerfiles or Singularity recipes) that describe how to re-produce those - images in the future. We use the following terminology, a "container image" - describes a container as stored at rest on a filesystem, a "tool" describes - one of the triples as described above. In practice, examples of "tools" - include CWL CommandLineTools, CWL Workflows, WDL workflows, and Nextflow - workflows that reference containers in formats such as Docker or - Singularity. + with a set of documents. Examples of documents include CWL (Common Workflow + Language) or WDL (Workflow Description Language) or NFL (Nextflow) that + describe how to use those images and a set of specifications for those + images (examples are Dockerfiles or Singularity recipes) that describe how + to reproduce those images in the future. We use the following terminology, a + "container image" describes a container as stored at rest on a filesystem, a + "tool" describes one of the triples as described above. In practice, + examples of "tools" include CWL CommandLineTools, CWL Workflows, WDL + workflows, and Nextflow workflows that reference containers in formats such + as Docker or Singularity. version: 2.0.0 tags: - name: GA4GH @@ -22,6 +22,7 @@ paths: '/tools/{id}': get: summary: 'List one specific tool, acts as an anchor for self references' + operationId: toolsIdGet description: >- This endpoint returns one specific tool (which has ToolVersions nested inside it) @@ -58,6 +59,7 @@ paths: '/tools/{id}/versions': get: summary: List versions of a tool + operationId: toolsIdVersionsGet description: Returns all versions of the specified tool tags: - GA4GH @@ -87,6 +89,7 @@ paths: '/tools/{id}/versions/{version_id}': get: summary: 'List one specific tool version, acts as an anchor for self references' + operationId: toolsIdVersionsVersionIdGet description: This endpoint returns one specific tool version tags: - GA4GH @@ -129,6 +132,7 @@ paths: /tools: get: summary: List all tools + operationId: toolsGet description: > This endpoint returns all tools available or a filtered subset using metadata query parameters. @@ -217,10 +221,11 @@ paths: $ref: '#/components/schemas/Tool' '/tools/{id}/versions/{version_id}/{type}/descriptor': get: - summary: Get the tool descriptor for the specified tool. + summary: Get the tool descriptor for the specified tool + operationId: toolsIdVersionsVersionIdTypeDescriptorGet description: >- - Returns the descriptor for the specified tool (examples include WDL, - CWL, or Nextflow documents). + Returns the descriptor for the specified tool (examples include CWL, + WDL, or Nextflow documents). tags: - GA4GH parameters: @@ -228,7 +233,7 @@ paths: required: true in: path description: >- - The output type of the descriptor. If not specified it is up to the + The output type of the descriptor. If not specified, it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata. Allowable values include @@ -247,8 +252,8 @@ paths: in: path required: true description: >- - An identifier of the tool version for this particular tool registry, - for example `v1` + An identifier of the tool version, scoped to this registry, for + example `v1` schema: type: string responses: @@ -273,6 +278,7 @@ paths: '/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}': get: summary: Get additional tool descriptor files relative to the main file + operationId: toolsIdVersionsVersionIdTypeDescriptorRelativePathGet description: >- Descriptors can often include imports that refer to additional descriptors. This returns additional descriptors for the specified tool @@ -287,7 +293,7 @@ paths: in: path required: true description: >- - The output type of the descriptor. If not specified it is up to the + The output type of the descriptor. If not specified, it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata. Allowable values are @@ -341,8 +347,10 @@ paths: $ref: '#/components/schemas/Error' '/tools/{id}/versions/{version_id}/{type}/tests': get: - summary: >- - Get an array of test JSONs (these allow you to execute the tool + summary: Get a list of test JSONs + operationId: toolsIdVersionsVersionIdTypeTestsGet + description: >- + Get a list of test JSONs (these allow you to execute the tool successfully) suitable for use with this descriptor type. tags: - GA4GH @@ -353,8 +361,8 @@ paths: description: >- The type of the underlying descriptor. Allowable values include "CWL", "WDL", "NFL", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL". For - example, "CWL" would return an array of ToolTests objects while - "PLAIN_CWL" would return a bare JSON array with the content of the + example, "CWL" would return an list of ToolTests objects while + "PLAIN_CWL" would return a bare JSON list with the content of the tests. schema: type: string @@ -399,11 +407,13 @@ paths: $ref: '#/components/schemas/Error' '/tools/{id}/versions/{version_id}/{type}/files': get: - summary: >- - Get an array of objects that contain the relative path and file type. - The descriptors are intended for use with the + summary: Get a list of objects that contain the relative path and file type + description: >- + Get a list of objects that contain the relative path and file type. The + descriptors are intended for use with the /tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path} endpoint. + operationId: toolsIdVersionsVersionIdTypeFilesGet tags: - GA4GH parameters: @@ -457,6 +467,7 @@ paths: '/tools/{id}/versions/{version_id}/containerfile': get: summary: Get the container specification(s) for the specified image. + operationId: toolsIdVersionsVersionIdContainerfileGet description: >- Returns the container specifications(s) for the specified image. For example, a CWL CommandlineTool can be associated with one specification @@ -507,6 +518,7 @@ paths: /metadata: get: summary: Return some metadata that is useful for describing this registry + operationId: metadataGet description: Return some metadata that is useful for describing this registry tags: - GA4GH @@ -523,6 +535,7 @@ paths: /toolClasses: get: summary: List all tool types + operationId: toolClassesGet description: | This endpoint returns all tool-classes available tags: @@ -551,10 +564,11 @@ components: limit: name: limit in: query - description: Amount of records to return in a given page. By default it is 1000. + description: Amount of records to return in a given page. schema: type: integer format: int32 + default: 1000 offset: name: offset in: query @@ -562,7 +576,7 @@ components: Start index of paging. Pagination results can be based on numbers or other values chosen by the registry implementor (for example, SHA values). If this exceeds the current result set return an empty set. If - not specified in the request this will start at the beginning of the + not specified in the request, this will start at the beginning of the results. schema: type: string @@ -617,14 +631,12 @@ components: properties: url: type: string - description: >- - The URL for this tool in this registry, for example - `http://agora.broadinstitute.org/tools/123456` + example: 'http://agora.broadinstitute.org/tools/123456' + description: The URL for this tool in this registry id: type: string - description: >- - A unique identifier of the tool, scoped to this registry, for - example `123456` or `123456_v1` + example: 123456 + description: 'A unique identifier of the tool, scoped to this registry' organization: type: string description: The organization that published the image. @@ -650,7 +662,8 @@ components: contains: description: >- An array of IDs for the applications that are stored inside this - tool (for example `https://bio.tools/tool/mytum.de/SNAP2/1`) + tool + example: 'https://bio.tools/tool/mytum.de/SNAP2/1' type: array items: type: string @@ -687,19 +700,18 @@ components: description: The name of the version. url: type: string - description: >- - The URL for this tool in this registry, for example - `http://agora.broadinstitute.org/tools/123456/1` + description: The URL for this tool in this registry + example: 'http://agora.broadinstitute.org/tools/123456/1' id: type: string description: >- An identifier of the version of this tool for this particular tool - registry, for example `v1` + registry + example: v1 image: type: string - description: >- - The docker path to the image (and version) for this tool. (e.g. - quay.io/seqware/seqware_full/1.1) + description: The docker path to the image (and version) for this tool + example: quay.io/seqware/seqware_full/1.1 registry_url: type: string description: >- @@ -758,9 +770,9 @@ components: type: string description: >- Optional url to the underlying tool descriptor, should include - version information, and can include a git hash (e.g. + version information, and can include a git hash + example: >- https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl - ) ToolTests: type: object description: >- @@ -778,7 +790,7 @@ components: Optional url to the test JSON used to test this tool. Note that this URL should resolve to the raw unwrapped content that would otherwise be available in test. - test-tool-url: + test_tool_url: type: string description: >- Optional url to the test workflow that will exit successfully if @@ -799,9 +811,9 @@ components: type: string description: >- Optional url to the file used to build this image, should include - version information, and can include a git hash (e.g. + version information, and can include a git hash + example: >- https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile - ) Metadata: type: object description: Describes this registry to better allow for mirroring and indexing.