接口开发规范及接口测试

一、接口开发规范

（一）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/