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

SpringBoot中配置Swagger

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

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-annotations</artifactId>
			<version>1.5.22</version>
		</dependency>
		<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-models</artifactId>
			<version>1.5.22</version>
		</dependency>

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<ResponseMessage> 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<T> {
    /**
     * 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