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?

I am using the following versions: 1.5.9 1.5.22and openapi-generator-maven-plugin 4.3.1 — Andrei Ion, Jun 04 '21 at 06:32
did I understand properly that you generate java api using openapi spec, and then openapi-ui generates openapi spec using java api? O_o. BTW, there was a bug in openapi-ui [String with format byte (base64) is being an array of strings and not a string #1559](https://github.com/springdoc/springdoc-openapi/issues/1559) — Andrey B. Panfilov, Sep 01 '22 at 16:30

dur · Answer 1 · 2022-09-01T17:31:03.970

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:

There are also several issues for SpringFox:

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

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

1 Answers1