如何为Swagger API响应指定泛型类

Question

我有大约40个具有类似基本响应结构的API,如下所示:

{
    "lastAccessed": "2015-30-08:14:21:45T",
    "createdOn": "2015-30-07:09:04:10T",
    "lastModified": "2015-30-08:14:21:45T",
    "isReadOnly": "false",
    "usersAllowed" : ["Tim", "Matt", "Christine"];
    "noOfEntries": 1,
    "object": [
        "ObjectA": {
             //here object A has its own model
         }
    ]
}

所以我有一个基类响应类,它采用类型T的泛型,如下所示:

public class Response<T> {
    @ApiModelProperty(value="Last time accessed")
    private String lastAccessed;
    @ApiModelProperty(value="Time when Created ")
    private String createdOn;
    private String lastModified;
    @ApiModelProperty(value="Created on")
    private boolean isReadOnly;
    @ApiModelProperty(value="Users that has access to the object.")
    private List<String> usersAllowed;
    private int noOfEntries;
    private T object;

    //getters and setters
}

因此对于API A,它返回具有自己字段的Object类型,我将返回Response作为控制器中的API响应:

  public class A {
    @ApiModelProperty(value="Name")
    private String name;
    @ApiModelProperty(value="OID")
    private String id;    
    //getters and setters
}    

在控制器中:Response data = new Response(); ResponseEntity response = new ResponseEntity <>(data,HttpStatus.OK);

有没有办法招摇我可以递归地指定响应对象的模型？例如,我可以使用注释@ApiOperation(response = Response.class)但是没有A的模型.

Answer 1

我知道这是一篇旧帖子,但对于其他寻找答案的人来说:

这可以为List,Set和Map响应对象完成,但是将忽略具有泛型类型的任何其他类类.如果您使用这三个中的任何一个,则在responseContainer字段中指定它们,并在字段中指定推断类型response.

@ApiResponse(code = 200, responseContainer="List", respone=java.lang.String.class)

Answer 2

我正在使用swagger 2，下面为我解决了这个问题。

从和中都删除“ response ”属性。然后swagger将根据方法存根自动为您生成200的响应类（无论响应类中是否使用泛型）。@ApiResponse@ApiOperation

@ApiOperation(value = "what your operation does")

@ApiResponses(value = { @ApiResponse(code = 200, message = "Success message") })

更新：您可以解决此简单的问题。只是说您要输出Response<MyClass>为响应返回类型。你可以做，

• 在控制器类中，指定一个空的私有类，如下所示

  private MyResponseClass extends Response<MyClass>{}

• 对于大张旗鼓的规格，请这样指定，

  @ApiResponse(code = 200, respone=MyResponseClass.class)

请记住，目前，swagger不支持泛型。以上两个只是解决方法。

Answer 3

这个问题是在 2015 年提出的，但我在 2020 年一直在寻找同样的事情。:) 因此，我认为添加我在这里找到的内容是相关的。

据我所知，我正在使用springdoc-openapi-ui(1.5.0)，它依赖于 Swagger JAR。由于公共响应类采用 generic T，因此实际的 API 方法必须定义预期的类型。例如，Response<Account>。

如果这也是您的场景，那么不定义 的schema属性@ApiResponse -> @Content似乎会使 Swagger 检查泛型类型并将其包含在架构中。同样的事情也适用于 Swagger 注释@RequestBody -> @Content