API中心 API Hub-易用性:API描述信息必须易于理解,表述准确

时间:2025-01-14 15:42:03

API描述信息必须易于理解,表述准确

本条规则是Should类型的扩展规则,可提升API调用者的使用体验。

  • API描述信息要易于理解,字面表述准确,能说明API的用途,场景及约束。
  • API描述信息建议使用Markdown格式编写,便于生成对应API文档,API描述信息长度建议不超过2000字符。

例如:发布API用于查询虚拟机列表。良好的API描述应为“通过虚拟机名称、IP地址、虚拟机型号查询当前租户下的虚拟机列表,列表包括虚拟机名称,所属VPC、虚拟机IP、虚拟机型号、操作系统版本。”

support.huaweicloud.com/productdesc-apihub/apihub_01_0025.html