How to specify OpenAPI for binary download in angular

Question

I have a method to download a binary file. This currently has the following spec in openapi.yaml:

  /processing/getZippedReports:
    post:
      tags:
      - ProcessingRest
      description: Get the reports
      operationId: getZippedReports
      requestBody:
        description: The list of items for which to get the HTML
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        200:
          description: file with zipped reports
          content:
            application/octet-stream: {}

The generated typescript-angular code contains this call to httpClient:

return this.httpClient.post<any>(`${this.configuration.basePath}/processing/getZippedReports`,
    requestBody,
    {
        withCredentials: this.configuration.withCredentials,
        headers: headers,
        observe: observe,
        reportProgress: reportProgress
    }
);

This way, angular seems unable to receive the binary content. I had to change the httpClient, use the non-type-variable signature of post and add responseType: blob to the parameters

return this.httpClient.post(`${this.configuration.basePath}/processing/getZippedReports`,
    requestBody,
    {
        withCredentials: this.configuration.withCredentials,
        headers: headers,
        observe: 'response',
        responseType: 'blob',
        reportProgress: reportProgress
    }
);

Is this a bug / missing feature in Swagger codegen or should I change the openapi definition to get working angular code?

Troytroyer

Try replacing empty response schema {} with a schema with type: string + format: binary. Does this help? – Markup

Yes, this indeed changes the signature of the HttpClient post request. Please post as answer, so I can accept – Troytroyer

Answer 1

To indicate that the response is a binary file, use a schema with type: string with format: binary.

          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

Markup

I'm having the same issue as the original poster. I've tried this @Helen, as it's marked as the accepted answer, but still doesn't include responseType: 'blob' in generated code. Any help? – Crutcher

Answer 2

It seems there is a x-is-file Vendor Extensions, i found it in the sourcecode, but no docs about it. Which leads to correct responseType definition in the controllerService.ts

        "responses": {
            "default": {
                "x-is-file": true,
                "description": "default response",
                "content": {
                    "application/octet-stream": {
                        "schema": {
                            "type": "file"
                        }
                    }
                }
            }
        },

Bushhammer

Answer 3

@wutzebaer was right about x-is-file

This is the definition in swagger 2.0

     responses:
        200:
          description: OK
          x-is-file: true
          schema:
            type: string
            format: binary

This generates

return this.httpClient.request('post',`${this.basePath}/member/generate_report_download`,
            {
                body: body,
                params: queryParameters,
                responseType: "blob", <--- Correct response type
                withCredentials: this.configuration.withCredentials,
                headers: headers,
                observe: observe,
                reportProgress: reportProgress
            }
        );

Vachel

Thank you, this works. I am pretty sure that x-is-* and x-has-* properties are internals and should not be put in the openapi specification. They are set up by codegen according to other properties. This is a workaround against a bug in swagger-codegen. – Loner