SpringBoot从入门到精通教程（二十六）- 全局header/body接口请求参数+Swagger2集成/接口规范用法

秒速五厘米 2021-10-15 03:27 389阅读 0赞

# 需求背景 #

> 在实际服务端API接口项目开发过程中，会有一些项目约定规范用法Tips，这次整理分享一下我过去使用过的，希望对你有用

# 问题痛点 #

*  项目开发时，没有统一参数规范约定，App对接成本、代码维护成本太高
 *  过去开发人员写代码时，要写很多必须要写但是又重复的代码，比如构造函数、getter/setter方法等
 *  一个接口返回时，无论内部是返回成功、失败、异常等，都统一返回了http状态码200，导致当集成监控工具时（因为监控工具一般是检测http状态码），无法监控区分，需要二次自定义开发/写脚本等

# Tips技术点 #

**1. 接口参数规范**

*  请求服务端接口时，统一使用全局header/body接口请求参数
 *  body参数统一使用DTO对象传输，使用注解@NotEmpty进行参数空校验

**2. 开发代码规范**

*  使用lombok组件，让代码更简洁，实现优雅编码
 *  接口返回值需区分http状态码200

**3. 集成swagger**

十分简单、简洁易用的在线接口文档组件swagger

Swagger入门教程用法：[SpringBoot从入门到精通教程（二十四）- Swagger集成用法][SpringBoot_- Swagger]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70][]

# 代码演示 #

**1. 项目目录结构**

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1][]

**2. pom.xml依赖组件**

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    	<modelVersion>4.0.0</modelVersion>
    
    	<parent>
    		<groupId>com.md</groupId>
    		<artifactId>spring-boot2-parent</artifactId>
    		<version>0.0.1-SNAPSHOT</version>
    		<relativePath>../pom.xml</relativePath>
    	</parent>
    
    	<artifactId>spring-boot2-swagger-req-params</artifactId>
    	<packaging>jar</packaging>
    
    	<name>spring-boot2-swagger-req-params</name>
    	<description>Spring Boot, MVC, Rest API for App</description>
    
    	<properties>
    		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    		<java.version>1.8</java.version>
    		<swagger.version>2.9.2</swagger.version>
    	</properties>
    
    	<dependencies>
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter</artifactId>
    		</dependency>
    		
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    		<dependency>
    			<groupId>net.sf.json-lib</groupId>
    			<artifactId>json-lib-ext-spring</artifactId>
    		</dependency>
    		
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>${swagger.version}</version>
    		</dependency>
    		
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>${swagger.version}</version>
    		</dependency>
    		
    		<dependency>
    			<groupId>com.github.xiaoymin</groupId>
    			<artifactId>swagger-bootstrap-ui</artifactId>
    			<version>1.9.3</version>
    		</dependency>
    		<dependency>
    			<groupId>org.projectlombok</groupId>
    			<artifactId>lombok</artifactId>
    		</dependency>
    		<dependency>
    			<groupId>com.alibaba</groupId>
    			<artifactId>fastjson</artifactId>
    		</dependency>
    	</dependencies>
    
    	<build>
    		<plugins>
    			<plugin>
    				<groupId>org.springframework.boot</groupId>
    				<artifactId>spring-boot-maven-plugin</artifactId>
    			</plugin>
    		</plugins>
    	</build>
    
    </project>

**3. 定义全局header参数**

在SwaggerConfig.java文件中，可以新增全局header参数（接口定义本身不需要再重复写了），所有接口会自动带上这个参数，比如userId或者token等

我这里使用了userId，完整代码如下：

package com.md.demo;
    
    import java.util.ArrayList;
    import java.util.List;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
    	/**
    	 * 创建一个Docket对象 调用select()方法， 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口
    	 * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理
    	 * 
    	 * @return
    	 */
    	@Bean
    	public Docket createRestApi() {
    		// 定义全局header参数
    		ParameterBuilder useridPar = new ParameterBuilder();
    		List<Parameter> pars = new ArrayList<>();
    		useridPar.name("userId").defaultValue("").description("用户id").modelRef(new ModelRef("string"))
    				.parameterType("header").required(false).build();
    		pars.add(useridPar.build());
    		
    		return new Docket(DocumentationType.SWAGGER_2)
    				.apiInfo(apiInfo()).select()
    				//如果不想将所有的接口都通过swagger管理的话，可以将RequestHandlerSelectors.any()修改为RequestHandlerSelectors.basePackage()
    				//.apis(RequestHandlerSelectors.any())
    				.apis(RequestHandlerSelectors.basePackage("com.md"))
    				.paths(PathSelectors.any())
    				.build()
    				.globalOperationParameters(pars);
    	}
    
    	@SuppressWarnings("deprecation")
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder()
    				// 标题
    				.title("SpringBoot2 中使用Swagger2 构建RESTful APIs")
    				// 简介
    				.description("This a demo for Swagger2")
    				// 服务条款
    				.termsOfServiceUrl("https://blog.csdn.net/hemin1003")
    				// 作者个人信息
    				.contact("Minbo.He")
    				// 版本
    				.version("1.0").build();
    	}
    }

**4. 定义DTO参数对象**

GetByIdDTO.java

package com.md.demo.dto;
    
    import javax.validation.constraints.NotEmpty;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel("根据用户ID标识查询")
    public class GetByIdDTO {
    
    	@ApiModelProperty(value = "用户ID标识", required = true)
    	@NotEmpty(message = "用户ID标识不能为空")
    	private String id;
    }

**5. 定义一个接口基类**

BaseController.java，接收参数合法性校验结果

package com.md.demo.util;
    
    import java.util.List;
    
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.ObjectError;
    
    /**
     * 基类
     * 
     * @author Minbo
     *
     */
    public class BaseController {
    
    	@SuppressWarnings({ "rawtypes", "unchecked" })
    	public JsonResult getJsonResult(Object model, BindingResult result) {
    		if (result.hasErrors()) {
    			StringBuilder stringBuilder = new StringBuilder();
    			List<ObjectError> allErrors = result.getAllErrors();
    			for (ObjectError objectError : allErrors) {
    				String defaultMessage = objectError.getDefaultMessage();
    				// 验证失败时提示内容一起拼接返回
    				stringBuilder.append(defaultMessage).append(";");
    			}
    			return new JsonResult(CodeEnums.PARA_ERR.getCode(), stringBuilder.toString(), model);
    		}
    		return null;
    	}
    }

**6. 定义一个http状态码工具类**

HttpStatusCodeUtil.java

package com.md.demo.util;
    
    import javax.servlet.http.HttpServletResponse;
    
    import lombok.extern.slf4j.Slf4j;
    
    /**
     * http响应码工具类
     * 
     * @author Minbo
     *
     */
    @Slf4j
    public class HttpStatusCodeUtil {
    
    	/**
    	 * 设置http响应码
    	 * 
    	 * @param response
    	 * @param statusCode
    	 */
    	public static void setCode(HttpServletResponse response, Integer statusCode) {
    		try {
    			response.setStatus(statusCode);
    		} catch (Exception ex) {
    			log.error("设置http响应码异常：" + ex.getMessage(), ex);
    		}
    	}
    }

**7. 接口访问层（**@RequestHeader和@RequestBody**）**

InitController.java

package com.md.demo.rest;
    
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.web.bind.annotation.RequestHeader;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.md.demo.util.JsonResult;
    
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    
    /**
     * @author Minbo
     */
    @RestController
    public class InitController {
    
    	protected static Logger logger = LoggerFactory.getLogger(InitController.class);
    
    	/**
    	 * http://localhost:9090/hello
    	 * 
    	 * @return
    	 */
    	@ApiOperation(value = "/hello 欢迎入口", httpMethod = "GET")
    	@RequestMapping(value = "/hello")
    	public String hello() {
    		logger.info("hello");
    		return "Hello greetings from spring-boot2-swagger-req-params";
    	}
    
    	@ApiOperation(value = "/getUserName 根据用户id获得用户的姓名", notes = "id不能为空", httpMethod = "GET")
    	@ApiImplicitParam(dataType = "string", name = "userId", value = "用户id", required = true)
    	@RequestMapping(value = "/getUserName")
    	@SuppressWarnings({ "rawtypes" })
    	public JsonResult getUserName(@RequestHeader String userId) {
    		String result = "hello " + userId + "，name=张三";
    		return JsonResult.ok(result);
    	}
    
    	/**
    	 * Swagger注解用法：
    	 * 
    	 * @Api：修饰整个类，描述Controller的作用
    	 * @ApiOperation：描述一个类的一个方法，或者说一个接口
    	 * @ApiParam：单个参数描述
    	 * @ApiModel：用对象来接收参数
    	 * @ApiProperty：用对象接收参数时，描述对象的一个字段
    	 * @ApiResponse：HTTP响应其中1个描述
    	 * @ApiResponses：HTTP响应整体描述
    	 * @ApiIgnore：使用该注解忽略这个API
    	 * @ApiError ：发生错误返回的信息
    	 * @ApiImplicitParam：一个请求参数
    	 * @ApiImplicitParams：多个请求参数
    	 */
    }

DemoController.java

package com.md.demo.rest;
    
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;
    
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.md.demo.dto.GetByIdDTO;
    import com.md.demo.service.IUserService;
    import com.md.demo.util.BaseController;
    import com.md.demo.util.HttpStatusCodeUtil;
    import com.md.demo.util.JsonResult;
    import com.md.demo.vo.UserVO;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import lombok.extern.slf4j.Slf4j;
    
    /**
     * @author Minbo
     */
    @RestController
    @RequestMapping("/demo")
    @Api(tags = { "接口-演示" })
    @Slf4j
    public class DemoController extends BaseController {
    
    	@Autowired
    	private IUserService userService;
    
    	@ApiOperation(value = "根据id获得用户信息", notes = "id不能为空", httpMethod = "POST")
    	@PostMapping(value = "/getUserById")
    	@SuppressWarnings({ "rawtypes", "unchecked" })
    	public JsonResult<UserVO> getUserById(@Validated @RequestBody GetByIdDTO dto, BindingResult result,
    			HttpServletRequest request, HttpServletResponse response) {
    		// 验证参数合法性（@NotEmpty注解）
    		JsonResult validResult = super.getJsonResult(dto, result);
    		if (validResult != null) {
    			// 设置http响应码，利于监控工具，不要统一使用200
    			HttpStatusCodeUtil.setCode(response, 4403);
    			return validResult;
    		}
    
    		// 获取用户ID
    		String userId = request.getHeader("userId");
    		log.info("获取用户ID，userId={}", userId);
    
    		// 逻辑处理
    		UserVO obj = this.userService.getUserById(dto);
    		return JsonResult.ok(obj);
    	}
    }

说明：

*  使用了注解@Validated，验证@NotEmpty
 *  使用了BindingResult对象，接收参数合法性检查结果
 *  如果参数校验不通过，则自定义设置http响应码
 *  使用了@Slf4j注解，可自动集成log日志输出

# 接口测试 #

1. 接口自动增加了全局header参数

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 2][]

2. 接口body参数用法，以及自动附加了接口数据模型说明

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 3][]

返回数据模型说明：UserVO.java类

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 4][]

3. 接口成功时：响应返回内容

各个字段及内容，会自动映射对应上，客户端接入时简单、高效

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 5][]

4. 接口异常时：响应返回内容

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 6][]

# 完整源码下载 #

我的[Github源码地址：][Github]

[https://github.com/hemin1003/spring-boot-study/tree/master/spring-boot2-study/spring-boot2-parent/spring-boot2-swagger-req-params][https_github.com_hemin1003_spring-boot-study_tree_master_spring-boot2-study_spring-boot2-parent_spring-boot2-swagger-req-params]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 7][]

# 下一章教程 #

[SpringBoot从入门到精通教程（二十七）- @Valid注解用法详解+全局处理器Exception优雅处理参数验证用法][SpringBoot_- _Valid_Exception]

# 该系列教程 #

[SpringBoot从入门到精通教程][SpringBoot]

Swagger入门教程用法：[SpringBoot从入门到精通教程（二十四）- Swagger集成用法][SpringBoot_- Swagger]

# 我的专栏 #

*  [SpringBoot系列专栏][SpringBoot 1]
 *  [高可用高并发实战][Link 1][专栏][Link 2]
 *  [微服务架构实战][Link 3]
 *  [DevOps实战专栏][DevOps]
 *  [程序化广告实战专栏][Link 2]

至此，全部介绍就结束了

\-------------------------------

[我的CSDN主页][CSDN]

[关于我][Link 4]（个人域名）

[我的开源项目集Github][Github 1]

期望和大家***一起学习，一起成长***，共勉，O(∩\_∩)O谢谢

欢迎交流问题，可加个人QQ 469580884，

或者，加我的群号 **751925591**，一起探讨交流问题

不讲虚的，只做实干家

Talk is cheap，show me the code

![20180411181545874][]

[SpringBoot_- Swagger]: https://blog.csdn.net/hemin1003/article/details/99637936
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70]: /images/20211015/8e089a36c3764f67a330539a8cc7057b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1]: /images/20211015/a9d8cf99e1974035b9ba865043f857fe.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 2]: /images/20211015/808353e0d31644209c99e5c0e06add45.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 3]: /images/20211015/f7f335f480f443c188b34b1d090ab941.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 4]: /images/20211015/a0293abab89e4bfa968fff1b794c5261.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 5]: /images/20211015/d7b8a2cb252c46b1b60d83f8b3f837f7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 6]: /images/20211015/3a61c71550c644d8b432d7a060797045.png
[Github]: https://github.com/hemin1003/spring-boot-study/tree/master/spring-boot2-study/spring-boot2-parent
[https_github.com_hemin1003_spring-boot-study_tree_master_spring-boot2-study_spring-boot2-parent_spring-boot2-swagger-req-params]: https://github.com/hemin1003/spring-boot-study/tree/master/spring-boot2-study/spring-boot2-parent/spring-boot2-swagger-req-params
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9oZW1pbi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 7]: /images/20211015/f85e0e0ad8a641cab5e015f6153276d7.png
[SpringBoot_- _Valid_Exception]: https://blog.csdn.net/hemin1003/article/details/103241022
[SpringBoot]: https://hemin.blog.csdn.net/column/info/40170
[SpringBoot 1]: https://blog.csdn.net/hemin1003/article/category/9291077
[Link 1]: https://blog.csdn.net/hemin1003/article/category/9292134
[Link 2]: https://blog.csdn.net/hemin1003/article/category/9290971
[Link 3]: https://blog.csdn.net/hemin1003/article/category/9292162
[DevOps]: https://blog.csdn.net/hemin1003/article/category/9292130
[CSDN]: https://blog.csdn.net/hemin1003
[Link 4]: http://heminit.com/about/
[Github 1]: https://github.com/hemin1003
[20180411181545874]: /images/20211015/2d8b6c6f781344258808a2d30fe1578d.png