Spring Boot使用Swagger做API管理，如何定义返回格式？

Question

问题描述

在使用swagger管理API的过程中确实可以很方便的管理API，但是返回的数据格式该如何定义啊？

问题出现的环境背景及自己尝试过哪些方法

我们定义了通用的返回格式，但是Data的内容是不一样的，在ApiOperation设置response的话不能显示具体内容，在方法的返回类型使用泛型定义返回格式的话感觉会很乱。

{
  "code": 0,
  "msg": "string"
  "data": {},
}

相关代码

@ApiOperation(value = "XX接口", httpMethod = "POST",response = Result.class)

public Result<XX> xxxx{
 return new Result<XX>(xx);
}

你期待的结果是什么？实际看到的错误信息又是什么？

感觉现在的做法非常别扭，有没有更好的解决办法？

Answer 1

泛型还好，没感觉得乱，而且现在还有工具可以直接swagger生成Typescript/js等客户端代码。

除了泛型，还有继承，但继承这种也因人而异。

class HaaRes extends Result<Haa> {
}

class HbbRes extends Result<Hbb> {
}


public HaaRes xxxx{
 return new HaaRes(xx);
}

public HbbRes yyyy{
 return new HbbRes(xx);
}

Answer 2

推荐使用 Rest 风格的返回结构。

• 如果请求成功，可以直接返回 data 里面的数据，没必要再包一层 code 和 msg，同时返回的 http code 为 2xx
• 当请求失败时，返回统一的错误提示，这时就可以使用 code 和 msg 给出具体的错误信息，并且将返回的 http code 设为 4xx 或是 5xx ，同时还可以定义 swagger 异常返回的 bean