Spring Boot中Swagger响应Schema配置：指定JSON结构而非字符串

我之前也碰到过一模一样的情况——用@RestController返回JSON格式的字符串，接口跑起来完全正常，但Swagger里就是只显示响应类型为string，看不到实际的JSON结构。这里有几个靠谱的解决办法：

方法一：修改方法返回类型为实际的DTO类 #

这是最规范的做法，既然你的服务返回的是JSON结构，直接把方法的返回类型从String改成对应的DTO类就行。@RestController会自动帮你完成Jackson序列化，同时Swagger会自动识别DTO的结构并展示出来。

比如假设你的MyService.getMyData()实际对应的数据结构是MyDataDto，修改后的代码如下：

@ApiOperation(value = "....", tags = {"Alarms"})
@PostMapping(value = "")
public MyDataDto getValuesByJsonString(@RequestBody Request request) {
    // 如果原Service返回的是String，可先反序列化为MyDataDto；或者直接修改Service返回DTO对象
    return myService.getMyData(request);
}

这样Swagger就会自动解析MyDataDto的字段，展示出完整的JSON响应结构了。

方法二：通过Swagger注解强制指定实际响应类型 #

如果因为遗留代码依赖等原因没法修改方法返回类型，可以通过Swagger的@ApiResponse注解明确指定响应对应的DTO类，强制让Swagger展示该类的结构。

你需要在@ApiResponses里补充200状态码的响应配置，把response参数设为你的目标DTO类：

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Success", response = MyDataDto.class),
    @ApiResponse(code = 400, message = "Bad request", response = ErrorDto.class),
    @ApiResponse(code = 404, message = "Location id not found", response = ErrorDto.class),
    @ApiResponse(code = 500, message = "Internal error")
})
@ApiOperation(value = "....", tags = {"Alarms"})
@PostMapping(value = "")
public String getValuesByJsonString(@RequestBody Request request) {
    return myService.getMyData(request);
}

这样即使方法返回的是String，Swagger也会根据你指定的MyDataDto来展示响应的JSON结构。

小细节提醒 #

另外注意下你代码里的小问题：构造函数的参数名MyService和成员变量myService大小写不一致，虽然不影响运行，但规范起见最好统一成小写开头的myService，避免混淆。

内容的提问来源于stack exchange，提问作者Bohdan Myslyvchuk