SpringBoot配置Swagger接口文档参数及返回值注释详细操作

目录

SpringBoot中配置SwaggerSwagger常用注解测试注解用途配置全局code返回状态码

用实体类接收参数或者返回数据配置

SpringBoot中配置Swagger

1. 导入依赖 官方推荐里说只需要前面两个依赖就可以了，但实测只导入上面两个依赖的话，后台会报依赖，网上查询加上下面两个依赖后不报异常了，原因未知。

io.springfox

springfox-swagger2

2.9.2

io.springfox

springfox-swagger-ui

2.9.2

io.swagger

swagger-annotations

1.5.22

io.swagger

swagger-models

1.5.22

2. 创建配置文件 注：

以下配置是配置了两个分组的接口文档，我创建的是一个是给前端人员的接口，一个是后台管理项目的接口，这样方便前端人员看接口时，只需要看他们所需的接口。

@Configuration

@EnableSwagger2

public class SwaggerConfig {

/****

* 前端接口配置

* @return

*/

@Bean

public Docket getClientDocket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

//分组名称

.groupName("ClientApi")

.select()

//扫描的包名称

.apis(RequestHandlerSelectors.basePackage("com.flower.controller.client"))

.paths(PathSelectors.any())

.build();

}

/****

* 后台管理接口配置

* @return

*/

@Bean

public Docket getBackgroundDocket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.groupName("BackgroundApi")

.select()

.apis(RequestHandlerSelectors.basePackage("com.gyd.flower.background"))

.paths(PathSelectors.any())

.build();

}

/***

* 构建 api文档的详细信息函数

* @return

*/

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("线上观花-api接口文档")

.description("powered by By gyd")

.termsOfServiceUrl("http://www.by-health.com/")

.contact(new Contact("MouYe", "url", "email"))

.version("1.0")

.build();

}

}

3. 测试 通过项目路径+swagger-ui.html打开接口文档

Swagger常用注解

@Api()

用于类，标识这个类是swagger的资源 ，主要用在controller类上，会在接口文档上显示当前类说明

@ApiOperation()

用于方法，在接口文档上面对接口进行说明，是swagger最主要的注解

@ApiParam()

用于方法，参数，字段说明，在方法上面对参数进行说明，会在接口文档上面显示参数的说明

@ApiModel()

用于类，表示对类进行说明，用于参数用实体类接收时，在接口文档上面会显示这个类里所有字段的说明

@ApiIgnore()

用于类，方法，方法参数，表示这个方法或者类被忽略，即不会显示在接口文档里面

@ApiImplicitParam()

用于方法，表示单独的请求参数，多数时候可以用@ApiParm替代

@ApiImplicitParams()

用于方法，包含多个 @ApiImplicitParam

@ApiResponses

同@ApiImplicitParams() ，用于方法，会在接口文档里面对当前接口返回的信息进行说明

测试注解用途

这是对实体类说明的注解，这样会在接口文档中显示当前类所有字段的说明

配置全局code返回状态码

swagger默认显示的状态码可能不是我们项目设定的，那么可以根据自己的项目需求设定所有接口的返回码，如下例

@Bean

public Docket createRestApi() {

//设定全局code为0表示成功，200表示失败

List responseMessageList = new ArrayList<>();

responseMessageList.add(new ResponseMessageBuilder().code(0).message("成功").build());

responseMessageList.add(new ResponseMessageBuilder().code(200).message("失败").build());

return new Docket(DocumentationType.SWAGGER_2)

.globalResponseMessage(RequestMethod.GET, responseMessageList)

.globalResponseMessage(RequestMethod.POST, responseMessageList)

.enable(swaggerShow)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.any())

.paths(PathSelectors.any())

.build();

}

用实体类接收参数或者返回数据配置

当我们用实体类返回数据时，需要我们的VO对象为泛型类型，这样才会在接口文档里面展示这个实体类的各个字段意思，VO对象如下：

@AllArgsConstructor

@NoArgsConstructor

@Data

@ApiModel("Result")

public class Result {

/**

* 1.status状态值：代表本次请求response的状态结果。

*/

@ApiModelProperty("状态码")

private Integer status;

/**

* 2.response描述：对本次状态码的描述。

*/

@ApiModelProperty("描述")

private String msg;

/**

* 3.data数据：本次返回的数据。

*/

@ApiModelProperty("数据")

private T data;

/**

* 成功，创建ResResult：没data数据

*/

public static Result suc() {

Result result = new Result();

result.setResultCode(ResultCode.SUCCESS);

return result;

}

/**

* 成功，创建ResResult：有data数据

*/

public static Result suc(Object data) {

Result result = new Result();

result.setResultCode(ResultCode.SUCCESS);

result.setData(data);

return result;

}

/**

* 失败，指定status、desc

*/

public static Result fail(Integer status, String desc) {

Result result = new Result();

result.setStatus(status);

result.setMsg(desc);

return result;

}

/**

* 失败，指定ResultCode枚举

*/

public static Result fail(ResultCode resultCode) {

Result result = new Result();

result.setResultCode(resultCode);

return result;

}

/**

* 把ResultCode枚举转换为ResResult

*/

private void setResultCode(ResultCode code) {

this.status = code.code();

this.msg = code.message();

}

}

ResultCode是枚举类，这样可以灵活的设置的各种状态对应的状态码及提示，代码如下：

package com.mytest.test.enums;

public enum ResultCode {

/* 成功状态码 */

SUCCESS(0, "成功"),

/* 失败状态码 */

FAIL(200, "失败"),

/* 系统500错误*/

SYSTEM_ERROR(10000, "系统异常，请稍后重试"),

UNAUTHORIZED(10401, "签名验证失败"),

TEST(500, "测试异常"),

/* 参数错误：10001-19999 */

PARAM_IS_INVALID(10001, "参数无效"),

/* 用户错误：20001-29999*/

USER_HAS_EXISTED(20001, "用户名已存在"),

USER_NOT_FIND(20002, "用户名不存在");

private Integer code;

private String message;

ResultCode(Integer code, String message) {

this.code = code;

this.message = message;

}

public Integer code() {

return this.code;

}

public String message() {

return this.message;

}

}

这样在返回数据时，直接用泛型类返回，在接口文档中才会显示实体类中的各个字段的意思，如果是返回的map的话，暂时还没找到处理办法 当我们返回实体类时，比如实体类里有的字段是前端人员不需要的字段，而且返回的也是null，这时可以在实体类里面加入注解，让此实体类中某个字段为null时，自动不返回

//为null则不返回

@JsonInclude(JsonInclude.Include.NON_NULL)

//为空不返回

@JsonInclude(JsonInclude.Include.NON_EMPTY)

//此注解放在字段上面，则永远不会返回

@JsonIgnore

properties文件里面也可以设置全局返回规则

#为null不返回

spring.jackson.default-property-inclusion=non_null