Generic Response Types

[croman17]

When an API returns a generic response type swagger-core:

1. The swagger-core generated object name is not linked to the API definition response.
2. Does not provide a means to customize the name of the returned object.

Example:
ResponseBody<List> getTeamMemberNames(Long teamId);

Swagger-core generates:
schema object: ResponseBodyListString (not a name we would want to expose)

  "ResponseBodyListString" : {
    "type" : "object",
    "properties" : {
      "data" : {
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      }
    }
  },

API definition:
"/team/membernames" : {
"get" : {
"operationId" : "getTeamMemberNames",
"parameters" : [ {
"name" : "teamId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "integer",
"format" : "int64"
}
} ],
"responses" : {
"200" : {
"description" : "OK",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ResponseBody"
}
}
}
},
}
}
},

You can see above, that the API definition response returns "ResponseBody" the name of the generic class. Rather than the generated ResponseBodyListString object.

Current workaround: We define a custom "doc" class and use that in the Operation annotation.
This requires the doc class and the actual implementation are kept in-sync.

@Operation(summary = "Gets team member names", 
    description = "Gets list of team member names.",
    responses = {
         @ApiResponse(responseCode = "200", description = "OK", 
             content = @Content(schema = @Schema(implementation = TeamMemberNamesResponse.class))),
     })    

[idkw]

This is really bad ...
Generics are not supported properly due to this issue.
What can be done ? How can we help ?

[amjadaziz817]

@idkw @croman17 I am not sure if you were able to resolve the issue or still facing this issue. I was also stuck with this scenario and doing some POCs. I was able to handle this scenario by not providing content definition in the ApiResponse.
@Operation(summary = "Gets team member names", description = "Gets list of team member names.", responses = { @ApiResponse(responseCode = "200", description = "OK"), })

Can you try above definition and it should work for generic responses.

Spring boot version: 2.5.4
Spring doc openapi: 1.5.10

[chelsternp44]

I am seeing the similar issue.
Controller

@GetMapping( "/loads" )
public LoadPage getShipmentLoads

public class LoadPage extends Page<Load>

public class Page<T> {
     String one; //able to see in swagger
     ObjectClass foo; //able to see in swagger
     
     List<T> realInfo; //not able to see in swagger
}

Load class is simple POJO.

If I follow advice I've seen other places by creating a private class in the controller as such it works, but this is not a great solution since Page is in a separate library.

private static class SwaggerLoadPage {

        String one;
        ObjectClass foo;

        List<Load> results;
    }

We are currently trying to migrate from Springfox to OpenApi. This somehow works with SpringFox as is. I think this could also be tied to the fact that Page is in a different library and using different versions of Swagger....

[idkw]

I found the issue on my side, it appeared that if you annotate you class with a @Schema and a name springfox doesn't generate a distinct definition for every variant, but if you don't annotate it, it does generate a definition for every variant. Not sure if this is a bug though ?

TL; DR; :

Don't do this :

@Schema(name="Page")
public class ListResponse<T> {     
     List<T> data;
     // ... other fields
}

But do this :

public class ListResponse<T> {     
     List<T> data; 
     // ... other fields
}

Then when you have a controller with something like :

public ListResponse<Book> getBooks() {
   return new ListResponse<>(List.of(new Book("1")));
}

Then you'll get a proper definition of something like ListResponseBook

[chelsternp44]

unfortunately our generic field is nested in a class from a separate library that I don't think we can make changes to easily.

Also we were on SpringFox it was working but with springdoc-openapi it is not

[idkw]

@chelsternp44 while you work with the maintainer of the separate library to remove the @Schema annotation, you can remove it temporarily on your side at runtime using bytecode manipulation, have a look at https://uzxmx.github.io/add-or-remove-java-annotation-at-runtime.html

This is really hacky but at least it works

[chelsternp44]

It turns out that our issue is due to a javax annotation breaking it. We are no longer seeing the issue once we dealt with that.

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;

...
@XmlAccessorType(XmlAccessType.NONE)

[varunsufi]

@chelsternp44 Is there any update on this issue ??

[chelsternp44]

@varunsufi - I did not work on this. We figured out what we were dealing with was an issue on our end

[idkw]

@chelsternp44 Is there any update on this issue ??

Have you tried this workaround, it has been working great for us so far

#3323 (comment)

[chelsternp44]

@chelsternp44 Is there any update on this issue ??

Have you tried this workaround, it has been working great for us so far

#3323 (comment)

I don't really remember the details of working on this haha. But based on here #3323 (comment) I think we got it working. Long time ago.

[seabird86]

#3323 (comment)

Thank you for discussion for this issue. This is a workaround, but it's still so bad. More code, more class and definition and have to sync them.
But how micronaut can do ? https://micronaut-projects.github.io/micronaut-openapi/1.4.1/guide/index.html#schemasAndGenerics. Is this any plan and solution to fix it ?
@croman17 @idkw

• The swagger-core generated object name is not linked to the API definition response. -> Why does api definition only has ResponseBody ? why don't generate with ResponseBody$List$String. Because of swagger core ? I remember springfox can do it.

• Does not provide a means to customize the name of the returned object. -> new version of spring doc has @content(@Schema). However It can't write (implement= ResponseBody<List> .class) in annotation.

[seabird86]

     .....   
        text/plain:
              schema:
                $ref: '#/components/schemas/Response<Money>'
components:
  schemas:
    Response<Money>:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Money'
    Money:
      type: object
      properties:
        amount:
          type: integer
          format: int32

I see in micronaut, it happen like this