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

2023-09-19 18:35| 来源: 网络整理| 查看: 265

目录 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

【本文地址】

公司简介

联系我们