基于Spring框架的Swagger流程应用

给Mock系统的正常请求及响应全流程数据
很多时候，如果你能在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统，直接将这些模拟数据录入到Mock系统中，那将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。

通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细，如果你把每个出入参数的示例值都配上，那前端就可以直接在接口文档中拿到模拟数据。

#####Controller代码
@Override
@ApiOperation(value = “post请求调用示例”, notes = “invokePost说明”, httpMethod = “POST”)
public FFResponseModel invokePost(@ApiParam(name=“传入对象”,value=“传入json格式”,required=true) @RequestBody @Valid DemoDto input) {
log.info("/testPost is called. input=" + input.toString());
return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
}

#####接口请求入参对象
@Data
@ApiModel(value=“演示类”,description=“请求参数类” )
public class DemoDto implements Serializable {

private static final long serialVersionUID = 1L;

@NotNull
@ApiModelProperty(value = "defaultStr",example="mockStrValue")
private String strDemo;

@NotNull
@ApiModelProperty(example="1234343523",required = true)
private Long longNum;

@NotNull
@ApiModelProperty(example="111111.111")
private Double doubleNum;

@NotNull
@ApiModelProperty(example="2018-12-04T13:46:56.711Z")
private Date date;

}

#####接口请求出参公共类
@ApiModel(value=“基础返回类”,description=“基础返回类”)
public class FFResponseModel implements Serializable {

private static final long serialVersionUID = -2215304260629038881L;
// 状态码
@ApiModelProperty(example="成功")
private String code;
// 业务提示语
@ApiModelProperty(example="000000")
private String msg;
// 数据对象
private T data;

…
}

#####接口请求出参实际数据对象
@Data
public class DemoOutputDto {

private String res;

@NotNull
@ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
private String outputStrDemo;

@NotNull
@ApiModelProperty(example="6666666",required = true)
private Long outputLongNum;

@NotNull
@ApiModelProperty(example="88888.888")
private Double outputDoubleNum;

@NotNull
@ApiModelProperty(example="2018-12-12T11:11:11.111Z")
private Date outputDate;

}
效果图
模拟请求数据报文：


模拟返回数据报文：

总结
其实归根到底，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。