From c84fdcfc884b4134001454e4ebd2d55109cb2a05 Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexander.kanitz@alumni.ethz.ch>
Date: Tue, 21 May 2024 22:00:10 +0200
Subject: [PATCH] fix: rectify "GET .../files" response schema (#249)

Fixes #248

### Description

Replaced response schema for [`GET .../files`](https://github.com/ga4gh/tool-registry-service-schemas/blob/1dd4bf806f98fa2e3d224d1976f6179de5cd46d6/openapi/openapi.yaml#L322-L370) with content type 'application/zip`.

Previously:

```yaml
application/zip:
  schema:
    type: array
    items:
      $ref: "#/components/schemas/ToolFile"
```

Proposed:

```yaml
application/zip:
  schema:
    type: string
    format: binary
```

### Motivation

From the [Swagger UI documentation] on file uploads:

> Files use a `type: string` schema with `format: binary` or `format: base64`, depending on how the file contents will be encoded.

Some other references to relevant discussions and uses of `type: string` and `format: binary` for representing binary file objects in request body or response schemas:
- https://spec.openapis.org/oas/v3.0.3#considerations-for-file-uploads
- https://github.com/swagger-api/swagger-ui/issues/5636
- https://azure.github.io/autorest/openapi/howto/binary-payload.html
- https://docs.visionlabs.ai/luna/v.5.24.1/ServiceManuals/APIDevelopmentManual/openapi_spec.html
- https://hyperfoil.io/docs/restapi.html
---
 openapi/openapi.yaml | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml
index 3cac981..7caf30e 100644
--- a/openapi/openapi.yaml
+++ b/openapi/openapi.yaml
@@ -357,9 +357,8 @@ paths:
                   $ref: "#/components/schemas/ToolFile"
             application/zip:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/ToolFile"
+                type: string
+                format: binary
         "404":
           description: The tool can not be output in the specified type.
           content: