Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Wrong response schema for "GET .../files" with "application/zip" #248

Closed
uniqueg opened this issue May 21, 2024 · 0 comments · Fixed by #249
Closed

Wrong response schema for "GET .../files" with "application/zip" #248

uniqueg opened this issue May 21, 2024 · 0 comments · Fixed by #249

Comments

@uniqueg
Copy link
Collaborator

uniqueg commented May 21, 2024

While looking at the specs for this response to #247, I found the following glitch in the description of response schemas for the GET .../files operation:

"/tools/{id}/versions/{version_id}/{type}/files":
  get:
    ...
    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. Returns a zip file of all files when format=zip is specified.
    ...
    responses:
      "200":
        description: The array of File JSON responses.
        content:
          ...
          application/zip:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/ToolFile"

Shouldn't the schema for the application/zip response rather be something like this?

schema:
  type: string
  format: binary

I'll create a PR.

┆Issue is synchronized with this Jira Story
┆Project Name: Zzz-ARCHIVE GA4GH tool-registry-service
┆Issue Number: TRS-71

uniqueg added a commit that referenced this issue May 21, 2024
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
- swagger-api/swagger-ui#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
denis-yuen pushed a commit that referenced this issue May 21, 2024
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
- swagger-api/swagger-ui#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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant