swagger2 统一默认 Response Code
项目中通常定义一个返回对象 Result,对返回对象的说明可以通过 @ApiResponse 进行说明如下，为每个类都指定精准但比较麻烦，可以通过统一配置的方式为每个请求附带默认的返回值说明。
@ApiResponses({ @ApiResponse(code = 200, message = "code字段值，描述：成功"), })
复制代码
@Datapublic Result<T>{ Integer code; String desc; T content;}
复制代码
API 文档 SpringBoot 集成 knif4j UI 框架 knife4j 文档
pom 依赖
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <!--在引用时请在maven中央仓库搜索3.X最新版本号--> <version>3.0.2</version></dependency>
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>xxx</version></dependency>
复制代码
通过 globalResponses 来设置统一的 Response 返回业务编码
swagger 配置文件 RequestHandlerSelectors.basePackage 扫描路径 RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 方法上有 ApiOperation 的注解
package com.dogs.doc.config;
import java.util.ArrayList;import java.util.List;
import com.dogs.doc.enums.ResponseCodeEnums;import io.swagger.annotations.ApiOperation;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.http.HttpMethod;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.builders.ResponseBuilder;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Response;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;
@Configurationpublic class Swagger2Config {
@Bean public Docket createRestApi() {
List<Response> globalResponses = new ArrayList<>(); for (ResponseCodeEnums item : ResponseCodeEnums.values()) { globalResponses.add(new ResponseBuilder() .code(String.valueOf(item.getCode())) .description(item.getDesc()) .build()); }
return new Docket(DocumentationType.OAS_30) .useDefaultResponseMessages(true) .globalResponses(HttpMethod.GET, globalResponses) .globalResponses(HttpMethod.POST, globalResponses) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.dogs.doc.controller")) .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build();
}
private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Dogs APIs") .description("knife4j") .termsOfServiceUrl("http://www.baidu.com") .version("3.0") .build(); }
}
复制代码
统一返回值枚举
ResponseCodeEnums.java
package com.dogs.doc.enums;
import lombok.Getter;
@Getterpublic enum ResponseCodeEnums {
/** * ResponseCodeEnums 返回业务编码 */ CODE_500(500,"你是否还会在灯火下守候……"), CODE_800001(800001,"测试业务编码800001"), CODE_800002(800002,"测试业务编码800002"), ;
int code; String desc;
ResponseCodeEnums (int code, String desc) { this.code = code; this.desc = desc; }}
@ApiResponse 可以为每个接口指定特别的返回值，一般都放到Enum中@RestControllerpublic class DocController {
@ApiOperation("Response测试返回信息") @ApiResponses({ @ApiResponse(code = 600100,message = "那个特别的你") }) @GetMapping("/rep") public Object apiResponse(){
return "rep"; }}
复制代码
运行项目 访问 localhost:8080/doc.html 查看文档
doc 文档每个请求都会带有默认的 code、desc,方便前端联调。
评论