API接口查询与测试

朱雀 2022-04-04 15:24 343阅读 0赞

当接口定义完成，可以使用工具生成接口文档，前端人员查看接口文档即可进行前端开发，这样前端和服务人员并行开发，大大提高了生产效率。

本章节介绍两种接口开发工具，Swagger和Postman

## 一. Swagger ##

### 1.1 **Swagger介绍** ###

OpenAPI规范（OpenAPI  Speciﬁcation  简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上（[https://github.com/OAI/OpenAPI-Speciﬁcation][https_github.com_OAI_OpenAPI-Speci_cation]）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 ([https://swagger.io/][https_swagger.io])

Spring Boot 可以集成Swagger，生成Swagger接口，Spring  Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

### 1.2 Swagger常用注解 ###

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口@ApiParam：单个参数描述  @ApiModel：用对象来接收参数  @ApiModelProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述  @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性：

<table style="margin-left:58.9pt;width:483.25pt;"> 
 <tbody> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> 属性 </td> 
 <td style="vertical-align:top;width:69.05pt;"> 取值 </td> 
 <td style="vertical-align:top;width:312.15pt;"> 作用 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> paramType </td> 
 <td style="vertical-align:top;width:69.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:312.15pt;"> 查询参数类型 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> path </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 以地址的形式提交数据 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:69.05pt;"> query </td> 
 <td style="vertical-align:top;width:312.15pt;"> 直接跟参数完成自动映射赋值 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> body </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 以流的形式提交 仅支持POST </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:69.05pt;"> header </td> 
 <td style="vertical-align:top;width:312.15pt;"> 参数在request headers 里边提交 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> form </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 以form表单的形式提交 仅支持POST </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> dataType </td> 
 <td style="vertical-align:top;width:69.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:312.15pt;"> 参数的数据类型 只作为标志说明，并没有实际验证 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> Long </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> &nbsp; </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:69.05pt;"> String </td> 
 <td style="vertical-align:top;width:312.15pt;"> &nbsp; </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> name </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 接收参数名 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> value </td> 
 <td style="vertical-align:top;width:69.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:312.15pt;"> 接收参数的意义描述 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> required </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 参数是否必填 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:69.05pt;"> true </td> 
 <td style="vertical-align:top;width:312.15pt;"> 必填 </td> 
 </tr> 
 <tr> 
 <td style="background-color:#f8f8f8;width:102.05pt;"> &nbsp; </td> 
 <td style="background-color:#f8f8f8;width:69.05pt;"> false </td> 
 <td style="background-color:#f8f8f8;width:312.15pt;"> 非必填 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:102.05pt;"> defaultValue </td> 
 <td style="vertical-align:top;width:69.05pt;"> &nbsp; </td> 
 <td style="vertical-align:top;width:312.15pt;"> 默认值 </td> 
 </tr> 
 </tbody> 
</table>

### 1.3 Swagger接口定义 ###

修改接口工程中页面查询接口，添加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 extends RequestData {
    
    // 站 点 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;
    
    }

### 1.4 **Swagger接口测试** ###

Swagger接口生成工作原理：

1、系统启动，扫描到api工程中的Swagger2Conﬁguration类

2、在此类中指定了包路径com.xxx，找到在此包下及子包下标记有@RestController注解的controller类

3、根据controller类中的Swagger注解生成接口文档。

启动cms服务工程，查看接口文档，请求：http://localhost:31001/swagger-ui.html

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70 2][]

点击“分页查询页面列表”，打开接口详情

使用Swagger工具测试服务接口：

1.  在cms服务接口中打断点
2.  打开接口文档页面，输入请求参数，点击“Try it out”发起请求。

## 二.Postman ##

## 三.restLet ##

[https_github.com_OAI_OpenAPI-Speci_cation]: https://github.com/OAI/OpenAPI-Specification
[https_swagger.io]: https://swagger.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70]: /images/20220404/5482f6041758476b83fe813e91e3bd99.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70 1]: /images/20220404/3db519a1b8c24cc28a033ad7ac09f5eb.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3JpanU0NzEz_size_16_color_FFFFFF_t_70 2]: /images/20220404/30394e1d6ab542a7a804ac98f9035199.png