一、接口开发规范
(一)Api请求及响应规范
为了严格按照接口进行开发,提高效率,对请求及响应格式进行规范化。
- get 请求时,采用key/value格式请求,SpringMVC可采用基本类型的变量接收,也可以采用对象接收。
- Post请求时,可以提交form表单数据(application/x-www-form-urlencoded)和Json数据(ContentType=application/json),文件等多部件类型(multipart/form-data)三种数据格式,SpringMVC接收Json数据
使用@RequestBody注解解析请求的json数据。 - 响应结果统一信息为:是否成功、操作代码、提示信息及自定义数据。
5、响应结果统一格式为json。
(二)Api定义约束
Api定义使用SpringMVC来完成,由于此接口后期将作为微服务远程调用使用,在定义接口时有如下限制:
- @PathVariable 统一指定参数名称,如:@PathVariable(“id”) 2、@RequestParam统一指定参数名称,如:
@RequestParam(“id”)
二、接口测试
(一)Swagger介绍
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格
式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。
(https://github.com/OAI/OpenAPI-Specification)
Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周
期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger,生成Swagger接口,Spring Boot是Java领域的神器,它是Spring项目下快速构建
项目的框架。
(二)Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用 @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述 @ApiModel:用对象来接收参数 @ApiModelProperty:用对象接收参数时,描述对
象的一个字段 @ApiResponse:HTTP响应其中1个描述 @ApiResponses:HTTP响应整体描述 @ApiIgnore:使用
该注解忽略这个API @ApiError :发生错误返回的信息 @ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
@ApiImplicitParam属性:
(三)Swagger接口定义(实例代码)
- 创建Swagger2配置类
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.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注解。
@Api(value = "cms页面管理接口", description = "cms页面管理接口,提供页面的增、删、改、查")
public interface CmsPageControllerApi {
/**
* 页面查询
*/
@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);
}
- 在QueryPageRequest类中使用注解 ApiModelProperty 对属性注释:
@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接口生成工作原理:
- 系统启动,扫描到api工程中的Swagger2Configuration类
- 在此类中指定了包路径com.xuecheng,找到在此包下及子包下标记有@RestController注解的controller类
- 根据controller类中的Swagger注解生成接口文档
启动cms服务工程,查看接口文档,请求:http://localhost:31001/swagger-ui.html
(五)Postman
Postman是一款功能强大的http接口测试工具,使用postman可以完成http各种请求的功能测试。
官方地址:https://www.getpostman.com/