(Regression from 2.6 to 2.8) Class used in "implementation" attribute is not rendered in Schemas

[arungitan]

Describe the bug
in one of our apis, we have an alternate implementation class to be used to document the schema for a nested array of objects. This class is not used directly as an argument in any api; it is only used in the @Schema annotation.
In 2.6, the class is rendered correctly in schemas. But in 2.8, it is completely skipped from rendering in schemas although the refs for it are generated in the referencing schema. Hence we get errors such as "could not resolve reference: JSON pointer evaluation failed while evaluating token "ThingAssignment" against an ObjectElement."

Would like to know if this is a known issue that is already fixed (pls advise min version of springdoc having fix) or if this is a new issue?

To Reproduce
Steps to reproduce the behavior:

• What version of spring-boot you are using?

  3.5.0

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

  2.8.9

• What is the actual and the expected result using OpenAPI Description (yml or json)?

  In 2.6, both Thing and ThingAssignment schema are rendered in the schemas list of the json.
  However, in 2.8, 'Thing' is rendered but 'ThingAssignment' is NOT rendered.

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

  Hopefully this snippet is enough to understand and reproduce the problem. If not, pls let me know.
  DTO classes:

  @Schema(description = "User resource") 
  class User  {
         // ... other attributes ...
 
         @ArraySchema(
               arraySchema = @Schema(description = "List of Things assigned to the user", requiredMode =  RequiredMode.REQUIRED), 
                schema = @Schema(implementation = Thing.ThingAssignment.class)
          )
           public List<Thing> getThings() {
               return things;
            }
    }  
    
    @Schema(description = "Thing resource")
    class Thing  {
           // ... various attributes ... 

           @Schema(description = "Thing to be assigned to user")
            static class ThingAssignment extends Thing {
                 // same as Thing but uses different @Schema annotations 
                 // more suited for a nested object...  
             }
     }

Expected behavior

• A clear and concise description of what you expected to happen.

• What is the expected result using OpenAPI Description (yml or json)?

  As in 2.6, both Thing and ThingAssignment schema should be rendered in the schemas list of the json.

Screenshots
If applicable, add screenshots to help explain your problem.

N/A

Additional context

Just to be clear, I am not looking for suggestion to redesign the api/use a different dto etc. That is out-of-scope for this. Just want a fix for what regressed between 2.6 and 2.8.
For now we have used the workaround of overriding the default openapi 3.1 version to 3.0
springdoc.api-docs.version=openapi_3_0

[Mattias-Sehlstedt]

For now we have used the workaround of overriding the default openapi 3.1 version to 3.0
springdoc.api-docs.version=openapi_3_0

Could you please clarify if whether this fixed so that the exposed specification included ThingAssignment properly?

If that is the case, then the issue is that swagger-core (the external dependency that is responsible for converting Java-classes to OpenApi components) has different parsing logic for when introspecting @Schema annotations to a 3.0 specification or to a 3.1 specification. Specifically @ArraySchema is not meant to be used. Edit: @ArraySchema is not deprecated, it just seems that the issue it is not working properly within model introspection (@ApiResponse annotations and similar Controller-located annotations seems to work properly).

For future bug reports I would suggest that you ensure that you provide code that works out-of-the-box, since it speeds things up on the investigators end, but it also eliminates any possibility for misinterpretations.

I have adjusted the code so that instead of @ArraySchema it uses the regular @Schema, and it looks to produce something that is more close to the behavior of 3.0. Please get back with more details if that does not solve the issue entirely.

@Schema(description = "User resource")
class User {

    private List<Thing> things;

    @Schema(requiredMode = Schema.RequiredMode.REQUIRED, description = "List of Things assigned to the user", implementation = Thing.ThingAssignment.class)
    public List<Thing> getThings() {
        return things;
    }
}

@Schema(description = "Thing resource")
class Thing  {
    // ... various attributes ...

    @Schema(description = "Thing to be assigned to user")
    class ThingAssignment extends Thing {
        // same as Thing but uses different @Schema annotations
        // more suited for a nested object...
    }
}

[arungitan]

@Mattias-Sehlstedt thank you for the response.

Could you please clarify if whether this fixed so that the exposed specification included ThingAssignment properly?

yes, using the property setting for 3.0 format does generate the schema for ThingAssignment. Identical to springdoc 2.6.

Was not aware that ArraySchema should not be used for this purpose in 3.1 (is there a reference that explains where it should or should not be used? I am curious since ArraySchema annotation is still present in the library, right? we still see it in the swagger 2.2.30 that we have) - but will definitely try out your suggestion and let you know.

[Mattias-Sehlstedt]

I have no reference, just based on my own experience of trying to adjust for this issue when upgrading to 3.1. So I have not done a technical investigation.

One way to do it is to do an investigation would be to use

ResolvedSchema resolvedSchema3_0 = ModelConverters.getInstance(false)
     .resolveAsResolvedSchema(new AnnotatedType(User.class).resolveAsRef(false));
ResolvedSchema resolvedSchema3_1 = ModelConverters.getInstance(true)
    .resolveAsResolvedSchema(new AnnotatedType(User.class).resolveAsRef(false));

and then look at the inner workings of how swagger-core handle the two different scenarios.

But I have so far been happy with just using the regular @Schema annotation and letting the field type be used to derive whether it is an array or not.

[Mattias-Sehlstedt]

I have tried to investigate it a bit by going into the swagger-core repository, but I have not really become any wiser. Looks like it could be a more specific case of this issue? I have tried to investigate by looking at their test cases, but something as simple as changing this test to

@Test
public void readDataTypesProperty() {
  final Map<String, Schema> models = ModelConverters.getInstance(true).readAll(ModelWithModelPropertyOverrides.class);
  ...
  ...
  ...
  SerializationMatchers.assertEqualsToJson31(models, json);
}

completely breaks it and the resolved schema all of a sudden becomes

ModelWithModelPropertyOverrides:
  type: object
  properties:
    children:
      type: string
      items:
        $ref: "#/components/schemas/Children"

instead of the expected

Children:
  type: object
  properties:
    name:
      type: string
ModelWithModelPropertyOverrides:
  type: object
  properties:
    children:
      type: array
      items:
        $ref: "#/components/schemas/Children"

[jackwhelpton]

Maybe this is the fix? https://github.com/swagger-api/swagger-core/releases/tag/v2.2.38

[arungitan]

belatedly i am attaching a standalone app and some notes to clarify the cases that we see.

openapi-demo.zip

@Mattias-Sehlstedt yes, the broken test case you mentioned seems similar to the effect in my Option A attempt. Adding the implementation class attribute to @Schema breaks the implicit array detection.

@jackwhelpton yes, we see the description problem in my option B - the description in arraySchema attribute is not used although the description in the nested schema attribute IS used. However, this description problem is a relatively minor aspect of it for us compared to the fact that it doesn't render the ThingAssignment schema. (I believe Option B is the correct annotation approach - it works as intended in 3.0 but is broken in 3.1)

@Mattias-Sehlstedt Is it fair to say now that this is not a springdoc issue but confirmed as an issue in swagger-core? (the build is pulling springdoc 2.8.13 and swagger 2.2.36 in my local build.)