OpenAPI changed

Author: Travis CI User

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,18 +221,19 @@ 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:
         - name: type
           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,18 +564,19 @@ 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
       description: >-
         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.