How to Define a Byte Array in OpenAPI 3.0

When migrating your API from Swagger 2.0 to OpenAPI 3.0, you might encounter issues with representing a byte array in your DTOs. In Swagger 2.0, you could define a byte array field like this:

Job:
  type: object
  properties:
    body:
      type: string
      format: binary

This configuration allowed the Swagger code generator to produce a DTO with a byte[] for the body field. However, after switching to OpenAPI 3.0, the same definition can lead to the generated code requiring an org.springframework.core.io.Resource instead of a byte[]. This post explains how to define the type as a byte array (i.e. byte[]) and discusses a couple of solutions.

Why Does the Issue Occur?

In OpenAPI 3.0, the specification for a byte array field is represented as a string with a format of byte:

"body": {
  "type": "string",
  "format": "byte"
}

While this is valid in the specification, some code generators interpret it differently between Swagger 2.0 and OpenAPI 3.0. In particular, the OpenAPI 3.0 code generator may map this to org.springframework.core.io.Resource instead of a byte[]. This difference creates challenges when your codebase expects a serializable byte[].

Solutions to Maintain byte[] in Your DTO

Solution 1: Use a Custom Model Converter

If you are using the swagger-maven-plugin to generate your OpenAPI definition, you can address the mapping issue by implementing a custom ModelConverter. The converter adjusts the generated JSON to ensure that the field is defined as:

"body": {
  "type": "string",
  "format": "byte"
}

This approach involves:

• Creating a custom ModelConverter class.
• Adding it to your Maven plugin configuration using the <modelConvertors> tag in your pom.xml.

For more details on this approach, refer to the discussion on GitHub Issue #422 in the swagger-maven-plugin repository.

Solution 2: Understand the OpenAPI 3.0 Response Schema

When returning a byte array in your API, the OpenAPI 3.0 specification typically represents the response as follows:

"responses": {
  "200": {
    "description": "byte[] return example for OpenAPI 3.0",
    "content": {
      "*/*": {
        "schema": {
          "type": "string",
          "format": "byte"
        }
      }
    }
  }
}

This indicates that the expected response schema for a byte array is a string with format: byte. If you generate client code or DTOs using this definition, ensure that the generated code is compatible with your application’s expectations. In some cases, you may need to adjust your code or configuration to map the field to byte[].

Key Takeaways

• OpenAPI Definition: To represent a byte array, define the field as type: string with format: byte.
• Code Generation Impact: Be aware that migrating from Swagger 2.0 to OpenAPI 3.0 may change the mapping of the byte array field from byte[] to org.springframework.core.io.Resource.
• Custom Model Converters: Using a custom ModelConverter can help maintain the byte[] mapping by ensuring the generated OpenAPI JSON conforms to your expectations.
• Response Schema: OpenAPI 3.0 represents byte array responses differently, so adjust your client code or DTO mapping as needed.

Conclusion

Migrating from Swagger 2.0 to OpenAPI 3.0 can introduce subtle changes in how data types are represented. When dealing with byte arrays, it’s important to ensure that your API definition correctly specifies the field as a string with a byte format. If the code generator maps the type to Resource instead of byte[], consider using a custom ModelConverter or adjusting your project’s configuration. By following these steps, you can maintain consistency in your API DTOs and avoid runtime serialization issues.

Keywords

OpenAPI 3.0, byte array, Swagger 2.0, byte format, DTO, API migration, swagger-maven-plugin, ModelConverter, byte[], API documentation, Swagger Codegen, Spring Boot, OpenAPI byte, API design, API specification, code generation, REST API, API serialization, Maven plugin, Swagger issue

This guide is designed to be clear, informative, and optimized for search engines. If you have any questions or need further assistance, feel free to leave a comment below. Happy coding!