API文档的编写|1688文档示例

日常项目开发的过程中，接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记录接口协议等等。对于一个完整的项目，接口文档是至关重要的。那我们如何写好一份接口文档呢？今天就让我们说一说接口文档几个重要的要素。

1、接口概述
接口概述主要说明本接口文档涉及到的业务功能点，面向的阅读对象以及接口文档主要包括哪些业务的接口，可以让读者有一个直观的认识。如：本文档定义了中台系统面向外部接入方的数据协议接口，主要包括：用户注册接口、同步用户、授权认证等接口。适合阅读的对象为接入中台开发者或者外部合作方…。这样的一段描述，对于阅读者来说可以对整个接口文档有一个大概的认识。

2、权限说明
有的接口调用需要授权认证，在这部分需要进行说明。如果接口只是基于分配的token认证，那文档需要说明token的获取方式。如果接口需要进行签名认证，需要在这里说明签名的具体方法，如下图：

1688.item_get

公共参数

请求地址: 申请调用KEY地址

名称	类型	必须	描述
key	String	是	调用key（必须以GET方式拼接在URL中）
secret	String	是	调用密钥
api_name	String	是	API接口名称（包括在请求地址中）[item_search,item_get,item_search_shop等]
cache	String	否	[yes,no]默认yes，将调用缓存的数据，速度比较快
result_type	String	否	[json,jsonu,xml,serialize,var_export]返回数据格式，默认为json，jsonu输出的内容中文可以直接阅读
lang	String	否	[cn,en,ru]翻译语言，默认cn简体中文
version	String	否	API版本

请求参数

请求参数：num_iid=610947572360

参数说明：num_iid:1688商品ID
sales_data:&sales_data=1 获取近30天成交数据
agent:&agent=1 获取1688分销代发价格数据

1688API 文档示例

API地址:

调用示例：

参数说明

通用参数说明

version:API版本
key:调用key,测试key:test_api_key
api_name:API类型[item_get,item_search]
cache:[yes,no]默认yes，将调用缓存的数据，速度比较快
result_type:[json,xml,serialize,var_export]返回数据格式，默认为json
lang:[cn,en,ru] 翻译语言，默认cn简体中文
API:item_get 参数说明: num_iid:宝贝ID

此API目前支持以下基本接口：

item_get 获得1688商品详情
item_search 按关键字搜索商品
item_search_img 按图搜索1688商品（拍立淘）
item_search_suggest 获得搜索词推荐
item_fee 获得商品快递费用
seller_info 获得店铺详情
item_search_shop 获得店铺的所有商品
item_password 获得淘口令真实url
upload_img 上传图片到1688
item_search_seller 搜索店铺列表
img2text 图片识别商品接口
item_get_app 获取1688app上原数据
buyer_order_list 获取购买到的商品订单列表
cat_get 获得1688商品分类