fix: Java Byte to OAS integer data type

[jongmin-chung]

Description

Fixes: springdoc/springdoc-openapi#3052

This PR fixes an incorrect type mapping for Byte class in OpenAPI 3.1 schema generation.

Problem: The createProperty31() method in the BYTE enum was incorrectly returning a JsonSchema with type "string" and format "byte", which is not compliant with OpenAPI 3.1 specification.

Solution: Changed the type from "string" to "integer" for proper byte representation in OpenAPI 3.1. The byte type in OpenAPI 3.1 should be represented as an integer type, not a string with byte format.

Type of Change

• 🐛 Bug fix
• ✨ New feature
• ♻️ Refactor (non-breaking change)
• 🧪 Tests
• 📝 Documentation
• 🧹 Chore (build or tooling)

Checklist

• I have added/updated tests as needed
• I have added/updated documentation where applicable
• The PR title is descriptive
• The code builds and passes tests locally
• I have linked related issues (if any)

Screenshots / Additional Context

The image above is the image referenced by Micronut Docs.

[ewaostrowska]

Hi @jongmin-chung!
Thank you for pointing this out. It does seem like mapping a numeric byte to integer/int8 would be conceptually correct for OAS 3.1 and is a change we should consider.

I have added this issue to our backlog to do some further investigations.

Some aspects to be checked:

• The PR’s test asserts that @Schema(type="string", format="byte") on a byte field still yields integer/int8. If teams relied on forcing a base64 string for historical reasons, this is a behavior change.
• We need to consider interactions with tools such as linters, codegens and validators which may warn on int8 format. int8 it’s not one of the core formats from the spec text.
• We need to test the behavior of byte arrays

[jongmin-chung]

Hi @ewaostrowska

Note

It's a library that a lot of people use, so it took me a while to understand the code with my research.
Please understand. I wanted to comment a faster review.

The PR’s test asserts that @Schema(type="string", format="byte") on a byte field still yields integer/int8. If teams relied on forcing a base64 string for historical reasons, this is a behavior change.

Thanks for the feedback. Referring to the OpenAPI 3.1 specification (link), I noticed that contentEncoding: base64 is applied on top of a type: string.

From that perspective, it seems more consistent that a Java primitive byte should map to integer, rather than being represented as a base64 string. Personally, I think base64 semantics belong to String types only.

Could you please confirm if mapping Java byte → base64 string was intended as a team rule, or if moving to integer/int8 for OAS 3.1 would be acceptable? Happy to adjust the PR once the direction is clear.

We need to consider interactions with tools such as linters, codegens and validators which may warn on int8 format. int8 it’s not one of the core formats from the spec text.

It was something that I also thought about. — int8 is not one of the core formats listed in the OAS 3.1 specification, and using it may trigger warnings in linters, codegens, or validators. To avoid introducing a non-standard format, I will remove the format: int8 and simply use type: integer. (7e4544a)

For cases where we want to reflect Java’s byte range (-128 to 127), OAS 3.1 allows expressing that via minimum and maximum constraints on the integer, rather than a dedicated format.

# Alternative
public Schema createProperty31() {
    // OAS 3.1: use integer with explicit range for Java byte (-128..127), no non-standard format
    return new JsonSchema()
            .typesItem("integer")
            .minimum(java.math.BigDecimal.valueOf(-128))
            .maximum(java.math.BigDecimal.valueOf(127));
}

We need to test the behavior of byte arrays

As you said, when I tested the byte arrays, they changed in the same way that byte is converted to OAS. (Link)

I will raise PR to revise the test code and code as below change. I would appreciate it if you could check about the team background. Please also check the official OAS3.1 document I referred to.

I tried to match the I add test, but OAS2, OAS3_1 backward compatibility, so it's not a code I like 😂, but I wrote the results and tests I wanted. (eab93d7)

# byte
byte:
  type: integer

# byte[]
arrayOfByte:
  type: array
    items: 
      type: integer