OpenApi documentation converts byte[] in array of byte[]

Question

I generate a Java class from a YAML file describing the model with openapi-generator-maven-plugin.

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.3.1</version>
    <executions>
      <execution>
        <id>document-10-service</id>
        <phase>generate-sources</phase>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <inputSpec>${project.basedir}/src/openapi/server/v1.0/documents-1.0.yaml</inputSpec>
          <output>${project.build.directory}/generated-sources/document-10-service</output>
          <generateApis>true</generateApis>
          <generateApiTests>false</generateApiTests>
          <generateModelTests>false</generateModelTests>
          <generateApiDocumentation>false</generateApiDocumentation>
          <generateModelDocumentation>false</generateModelDocumentation>
          <generateSupportingFiles>true</generateSupportingFiles>
          <apiPackage>com.siemens.spice.documents.generated.api</apiPackage>
          <modelPackage>com.siemens.spice.documents.generated.model</modelPackage>
          <invokerPackage>com.siemens.spice.documents.generated</invokerPackage>
          <generatorName>spring</generatorName>
          <skipOverwrite>false</skipOverwrite>
          <configOptions>
            <sourceFolder>server</sourceFolder>
            <supportingFiles>ApiUtil.java</supportingFiles>
            <library>spring-boot</library>
            <dateLibrary>java8</dateLibrary>
            <interfaceOnly>true</interfaceOnly>
            <useBeanValidation>true</useBeanValidation>
            <hideGenerationTimestamp>true</hideGenerationTimestamp>
          </configOptions>
        </configuration>
      </execution>

I have the following model described in the YAML file:

 Document:
required:
  - documentMetaData
  - documentContent
type: "object"
properties:
  documentMetaData:
    $ref: "#/definitions/DocumentMetaData"
    description: "Document type information"
  documentContent:
    type: string
    format: byte
    description: "Base64 encoded document content"

This generates the following class which is ok:

public class DownloadDocument   {
  @JsonProperty("documentMetaData")
  private DocumentMetaData documentMetaData;

  @JsonProperty("documentContent")
  private byte[] documentContent;
}

But when entering the swagger-ui.html page and trying to get the documentation by click on the link:

enter image description here

it looks like this:

"DownloadDocument": {
            "required": [
                "documentContent",
                "documentMetaData"
            ],
            "type": "object",
            "properties": {
                "documentMetaData": {
                    "$ref": "#/components/schemas/DocumentMetaData"
                },
                "documentContent": {
                    **"type": "array",
                    "items": {
                        "type": "string",
                        "format": "byte"
                    }**
                }

The document content which is a byte[] is documented as an array of byte[] and when using this description in other app to generate an API client it generates a List<byte[]>.

I would expect the following format also in the OpenApi Specification/Description:

documentContent:
    type: string
    format: byte
    description: "Base64 encoded document content"

Can you please advice if this is a bug or if not how can be resolved?

Answer 1

If you have generated Java classes from a YAML file the Swagger UI should generate the origin YAML/JSON file.

Known Issues

There are several issues for OpenAPI Tools:

• OpenApi documentation converts byte[] in array of byte[]
• byte[] not correctly handled by openapi converter

There are also several issues for SpringFox:

• Response with a byte array does not work as expected
• byte array should have type string and format byte
• swagger-codegen-cli.jar dont understand ResponseEntity<byte[]>

There are also issues for springdoc-openapi:

• String with format byte (base64) is being an array of strings and not a string

Other implementations with issues:

• byte[] operation responses / model properties modelled incorrectly

Known work-arounds

• If you could change the Java classes, see byte[] not correctly handled by openapi converter :

  Just for reference, if you want to use the io.swagger.core.v3:swagger-annotations, then use this:

   @ApiResponse (description = "default response",
            content = @Content (schema = @Schema (type = "string",
                                                  format = "byte")))
  

  There is also a solution for non response type, see String with format byte (base64) is being an array of strings and not a string :

   @Schema(name = "message",  required = true, type = "string", format = "binary")
   @JsonProperty("message")
   @lombok.Builder.Default
   @NotNull
   private byte[] message = null; 
  

• If you could use Maven Plugin instead of Swagger UI to generate your OpenAPI YAML/JSON file, see Response with a byte array does not work as expected :

  I encountered a similar issue using the swagger maven plugin (from kongchen). I fixed it by defining an additional ModelConverter that verifies if it's a byte[] and then returns a ByteArrayProperty:

  There is also a solution for request parameter, see byte[] operation responses / model properties modelled incorrectly:

  It does this for Request bodies as well. Here is the fix for version 2.0.10:

Related questions

• How to declare binary data response content-type correctly?
• when using swagger codegen getting 'List<byte[]>' instead of simply 'byte[]'
• How to define byte array in OpenAPI 3.0