接口基础知识10：详解接口文档

课程大纲

一、接口文档简介

描述系统接口信息的文档，通常由‌后端开发人员编写，用于规定接口的规范，详细说明接口的逻辑和作用、如何调用接口。

接口文档包含的内容：

接口的逻辑和作用：简要描述接口的功能和用途。

请求方法：如‌GET、‌POST等，以及如何使用这些方法。

URL规范：接口的URL地址，包括必要的路径参数。

请求参数：需要传递的参数及其类型、是否必填等详细说明。

响应内容：接口返回的数据格式和字段说明。

错误代码：对接口可能出现的错误进行归类，便于快速定位和解决问题。

作为测试人员，最重要是会看接口文档。有2种比较常见的在线接口文档：showdoc、swagger。

二、showdoc接口文档

showdoc是常用的在线接口文档，可手动创建或自动生成API文档。示例如下（摘自showdoc官网）：

商户费率查询 简要描述： · 商户手续费查询接口 请求URL： · http://xx.com/app_center/common/queryFee.do?mchId=000000100537975&channelId=13 请求方式： · POST 参数： 参数名 必选 类型 说明 mchId 是 string 聚合商户号 channelId 是 string 支付渠道：12-支付宝，13-微信，27-银联扫码 返回示例： {     "head": {         "rd": "0",         "rm": "成功"     },     "body": [{         "device": "被扫支付",         "feeValue": "0.38"     }, {         "device": "微信公众号",         "feeValue": "0.38"     }, {         "device": "小程序支付",         "feeValue": "0.38"     }] } 返回参数说明： 参数名 类型 说明 device string 支付场景名称 feeValue string 手续费 备注： · 更多返回错误代码请看首页的错误代码描述

三、swagger接口文档

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化“RESTful风格的Web 服务”。通过注解或配置文件的方式，可以自动从源代码中生成接口文档，并提供了在线文档展示、参数校验和模拟请求等功能。（可以做简单的接口测试）

界面及操作，参考：https://httpbin.org/，里面基本涵盖各种类型接口，可进行测试。 

界面简洁

在线对一个接口做请求，测试一下：

参考文章：

1、《HTTP响应是什么？》

https://blog.csdn.net/m0_62617719/article/details/128191090