Type field missing from generated OpenAPI 3.1 schema with custom ModelResolver

[jackwhelpton]

Describe the bug

OpenAPI 3.1 docs omit type information.

To Reproduce
Steps to reproduce the behavior:

Given a simple POJO:

@Data
@Schema(name = "quantityInStatus", description = "Quantity in status model")
public class QuantityInStatus {

    @Schema(example = "10", description = "Created")
    private long created;
}

The OpenAPI 3.0 output is:

QuantityInStatus:
  description: Quantity in status model
  properties:
    created:
      description: Created
      example: 10
      format: int64
      type: integer
  type: object

For 3.1, we see only:

QuantityInStatus:
  description: Quantity in status model
  properties:
    created:
      description: Created
      example: 10
      format: int64
      type: integer

Observe the missing type information.

• What version of spring-boot you are using? 3.5.6

• What modules and versions of springdoc-openapi are you using?

  • 2.8.13 of springdoc-openapi-starter-webmvc-ui
  • 2.2.38 of swagger-core (updated/pinned in pom.xml)

• Provide with a sample code (HelloController) or Test that reproduces the problem

This test doesn't reproduce the actual schema generation part, but it may show the underlying cause.

@Schema
record TestResource(int quantity) {}

@Test
void shouldIncludeTypeWithOpenApi3_0() {
    ResolvedSchema resolvedSchema = ModelConverters.getInstance(false)
            .resolveAsResolvedSchema(new AnnotatedType(TestResource.class).resolveAsRef(false));

    String type = resolvedSchema.schema.getType();

    assertThat(type).isEqualTo("object");
}

@Test
void shouldIncludeTypeWithOpenApi3_1() {
    ResolvedSchema resolvedSchema = ModelConverters.getInstance(true)
            .resolveAsResolvedSchema(new AnnotatedType(TestResource.class).resolveAsRef(false));

    String type = resolvedSchema.schema.getType();

    assertThat(type).isEqualTo("object");
}

@Test
void shouldIncludeTypesWithOpenApi3_1() {
    ResolvedSchema resolvedSchema = ModelConverters.getInstance(true)
            .resolveAsResolvedSchema(new AnnotatedType(TestResource.class).resolveAsRef(false));

    Set<String> types = resolvedSchema.schema.getTypes();

    assertThat(types).containsExactly("object");
}

Observe that the ResolvedSchema for 3.1 has null type property (shouldIncludeTypeWithOpenApi3_1 fails), but instead populates the types set (shouldIncludeTypesWithOpenApi3_1 passes).

Is it possible the types field isn't being used when generating the actual docs?

[jackwhelpton]

I believe the type field can now be single-valued or an array, as per:

https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

Probably the doc generation logic for 3.1 should be serializing a single value if the types field has only a single element, although with a caveat for the new way of representing nullable fields, also mentioned in the link above:

# OpenAPI v3.1
type:
- "string"
- "null" 

[Mattias-Sehlstedt]

The pojo missing the type after being resolved to 3.1 is expected, as per the changes in 3.1 that you have referenced.

It is handled later when the pojo-specification is resolved to json/yaml. It can be seen by defining this as a controller

@RestController
public class TestApiController {

  @GetMapping(value = "/test2")
  public QuantityInStatus getQuantity() {
    return null;
  }

  @Data
  @Schema(name = "quantityInStatus", description = "Quantity in status model")
  public class QuantityInStatus {

    @Schema(example = "10", description = "Created")
    private long created;
  }

}

and then seeing that it gets resolved to the expected specification

{
  "openapi" : "3.1.0",
  "info" : {
    "title" : "OpenAPI definition",
    "version" : "v0"
  },
  "servers" : [ {
    "url" : "http://localhost",
    "description" : "Generated server url"
  } ],
  "paths" : {
    "/test2" : {
      "get" : {
        "tags" : [ "test-api-controller" ],
        "operationId" : "getQuantity",
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/quantityInStatus"
                }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "quantityInStatus" : {
        "type" : "object",
        "description" : "Quantity in status model",
        "properties" : {
          "created" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "Created",
            "example" : 10
          }
        }
      }
    }
  }
}

where the type if present when a 3.1 specification is generated.

[jackwhelpton]

Ah, OK, so I do need a reproducer using that last json/yaml stage, as I'm not seeing type information in the generated schema for my project when using 3.1.

Any pointers welcome: I'll update this comment once I have something more useful to share. My app itself has some fairly complex customization occurring, so ideally I'd want to avoid pulling all of that into a unit test.

Actually, one thing I'll do now is to run without those customization stages and see if the type information is restored for V3.1.

OK, now we're getting somewhere! Something in my customization stages is obviously b0rking the V3.1 output. Let me narrow that down.

[Mattias-Sehlstedt]

Yes a full Controller is always preferred, since that mimics the real scenario entirely. The ModelConverters approach is generally mostly helpful in trying to deduce whether a generation issue comes from swagger-core or not (so in this case it was of course interesting to see the type being moved, but it since the Controller works then it is most likely not the cause).

I would try to isolate (and obfuscate if you have sensitive data) a single endpoint where you see changes in the specification, and then share that as a minimalistic Controller. But if you have a number of customizers then it might be that those only properly handle the 3.0 pojo that swagger produces, and that they miss data for the changes that have come with 3.1. I.e., it might be that your customizers are not changing the pojos properly, or that they all of sudden customize the objects incorrectly.

[jackwhelpton]

OK, I've found the cause, and thought I had a sensible fix but that isn't working either. This is triggered when I have a customized ModelResolver thus:

@Bean
public ModelResolver modelResolver(ObjectMapper objectMapper) {
    var customTypeNameResolver = new TypeNameResolver() {

        @Override
        protected String nameForClass(Class<?> cls, Set<Options> options) {
            return super.nameForClass(cls, options);
        }

        @Override
        protected String nameForGenericType(JavaType type, Set<Options> options) {
            return super.nameForGenericType(type, options);
        }
    }

    return new ModelResolver(objectMapper, customTypeNameResolver);
}

Obviously I have my own logic here, but I can reproduce the issue by just delegating to the parent class. I thought the issue was using my application's object mapper on the last line here, but I switched that out for Json31.mapper() and the type information is still gone.

Aha! ModelResolver has a boolean property for 3.1 or not, even though it's not on the constructor. If I set that, we're good.

[jackwhelpton]

Yep, I'm going to close this, thanks for all your patience! Here's the fixed code on my side:

@Configuration
@RequiredArgsConstructor
@Slf4j
public class DocConfig {

    private final SpringDocConfigProperties springDocConfigProperties;

    ...

    @Bean
    public ModelResolver modelResolver(ObjectMapper objectMapper) {
        ...
        var resolver = new ModelResolver(objectMapper, customTypeNameResolver);
        resolver.setOpenapi31(springDocConfigProperties.isOpenapi31());

        return resolver;
    }
}