接口开发规范
Api请求及响应规范
为了严格按照接口进行开发，提高效率，对请求及响应格式进行规范化。
1、get 请求时，采用key/value格式请求，SpringMVC可采用基本类型的变量接收，也可以采用对象接收。
2、Post请求时，可以提交form表单数据（application/x-www-form-urlencoded）和Json数据（ContentType=application/json），文件等多部件类型（multipart/form-data）三种数据格式，SpringMVC接收Json数据
使用@RequestBody注解解析请求的json数据。
4、响应结果统一信息为：是否成功、操作代码、提示信息及自定义数据。
5、响应结果统一格式为json。
@PathVariable 统一指定参数名称，如：@PathVariable(“id”) 2、@RequestParam统一指定参数名称，如：
@RequestParam（“id”）
测试接口工具（测试接口返回的数据格式）
如果前端人员等待服务端人员将接口开发完毕再去开发前端内容这样做效率是
非常低下的，所以当接口定义完成，可以使用工具生成接口文档，前端人员查看接口文档即可进行前端开发，这样
前端和服务人员并行开发，大大提高了生产效率。
本章节介绍两种接口开发工具，Swagger和Postman。
一、Swagger依赖
<!-- 接口规范文档工具-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<!-- 接口规范文档工具-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
二、Swagger配置文件（使项目启用Swagger服务）
package com.xuecheng.api.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
/**
* API管理控件Swagger
* 开启接口规范的服务
*/
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描所有com.xuecheng包下有@RestController的类， 根据该类的方法生成接口文档
.apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("学成网api文档")
.description("学成网api文档")
// .termsOfServiceUrl("/")
.version("1.0")
.build();
}
}
三、Swagger接口定义（添加相关注解对方法参数和方法进行描述，使Swagger前端管理工具识别并展示）（这里的Swagger注解标识了接口， 实现它的类也能继承它的注解）
package com.xuecheng.api.cms;
import com.xuecheng.framework.domain.cms.request.QueryPageRequest;
import com.xuecheng.framework.model.response.QueryResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Component;
/**
* @author Huang
* @version 1.0
* @date 2020/3/18 11:29
* 方法接口
*/
@Component
@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {
//页面查询
//给予Swagger文档的接口描述提供信息
@ApiOperation("分页查询页面列表")
@ApiImplicitParams({
@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"),
@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest/*页面查询条件类型*/);
}
四、若方法中的参数是实体时，对该实体的注解
package com.xuecheng.framework.domain.cms.request;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @author Huang
* @version 1.0
* @date 2020/3/18 11:09
*/
@Data
public class QueryPageRequest {
//站点id
@ApiModelProperty("站点id")
private String siteId;
//页面ID
@ApiModelProperty("页面ID")
private String pageId;
//页面名称
@ApiModelProperty("页面名称")
private String pageName;
//别名
@ApiModelProperty("页面别名")
private String pageAliase;
//模版id
@ApiModelProperty("模版id")
private String templateId;
}
五、Swagger接口测试
Swagger接口生成工作原理：
1、系统启动，扫描到api工程中的Swagger2Configuration类
2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成接口文档。
启动cms服务工程，查看接口文档，请求：http://localhost:31001/swagger-ui.html（31001为项目端口）
点击分页查询页面列表查看接口详情
使用Swagger工具测试服务接口：
1）在cms服务接口中打断点
2）打开接口文档页面，输入请求参数，点击“Try it out”发起请求。
