API中心 API Hub-易用性:API文档按照模板进行写作

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

API文档按照模板进行写作

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

API对外开放时,API文档建议使用统一的模板,以便保持API参考文档的一致性,易于开发者理解。在API参考文档中必须包含如下内容:
  • API目录,包括本次提供API的列表信息。
  • API名称及API功能介绍。
  • API请求方法和URI。
  • API请求参数说明,包括Header、Query参数,需要明确字段内容和取值范围。
  • API请求Body内容,Body内容需要明确请求结构体内容及各个字段的取值范围。
  • API响应状态码,状态码及对应的说明。
  • API响应参数说明包括Header参数,需要明确字段内容和取值范围。
  • API正常响应Body内容,正常响应Body内容需要明确响应结构体内容及各个字段的取值范围。
  • API异常响应Body内容,异常响应Body中描述及说明。
support.huaweicloud.com/productdesc-apihub/apihub_01_0025.html