使用DescribeApiDoc查询API说明文档-API 网关-阿里云-API 网关(API Gateway)-阿里云帮助中心

查询指定API的服务说明文档。

接口说明

此功能面向调用 API 的用户，指定的 API 必须是发布到运行环境，且 Visibility=PUBLIC 的 API 或者被授权的 Visibility=PRIVATE 的 API
若您是调用 API 的用户，该接口返回您指定的 API 的服务信息及参数定义等详情信息。
若您是开放 API 的用户，那么调用该接口可以查看当前指定 API 在指定环境中运行的定义，可能与您现在修改中的 API 定义不同，是真正在环境中生效的定义。
若您是开放 API 的用户，由于该接口面向 API 调用者鉴权，所以您需要确认该 API 为 PUBLIC 类型或者您的相关 APP 已被授权。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

apigateway:DescribeApiDoc

get

*ApiGroup

acs:apigateway:{#regionId}:{#accountId}:apigroup/{#GroupId}

无

请求参数

名称	类型	必填	描述	示例值
GroupId	string	否	指定的分组编号	123
StageName	string	否	环境名称，可选值： RELEASE: 线上 TEST: 测试若不传入，则默认为 release。	RELEASE
ApiId	string	是	指定的 API 编号	3b81fd160f5645e097cc8855d75a1cf6

返回参数

名称	类型	描述	示例值
	object
ApiId	string	API 编号	b24be7e59a104e52bffbf432cc9272af
ResultType	string	返回类型	JSON
DisableInternet	boolean	设置 DisableInternet 为 true, 仅支持内网调用 API。设置 DisableInternet 为 false, 则不限制调用。创建 API 时默认为 false。	true
ResultSample	string	返回示例	{\n \"status\": 0,\n \"data\": {\n \"count\": 1,\n \"list\": [\n \"352\"\n ]\n },\n \"message\": \"success\"\n}
RegionId	string	API 分组所在的地域 ID	cn-hangzhou
ForceNonceCheck	boolean	设置 ForceNonceCheck 为 true, 请求时强制检查 X-Ca-Nonce，这个是请求的唯一标识，一般使用 UUID 来标识。API 网关收到这个参数后会校验这个参数的有效性，同样的值，15 分内只能被使用一次。可以有效防止 API 的重放攻击。设置 ForceNonceCheck 为 false，则不检查。创建 API 时默认为 false。	true
Visibility	string	可见性，取值为：PUBLIC、PRIVATE，分别表示公开、私有	PUBLIC
FailResultSample	string	后端服务失败返回应答的示例	{"errorCode":"fail","errorMessage":"param invalid"}
AuthType	string	安全认证方式，取值为：APP、ANONYMOUS，分别表示阿里云 APP、匿名	APP
RequestId	string	请求 ID	F253FB5F-9AE1-5DDA-99B5-46BE00A3719E
GroupId	string	API 分组编号	f51d08c5b7c84342905544ebaec26d35
GroupName	string	API 分组名称	会员时代交易服务
Description	string	API 描述	领克数字商城OMS-UAT
DeployedTime	string	发布时间	2022-07-13T16:00:33Z
StageName	string	环境名称，可选值： RELEASE: 线上 TEST: 测试	RELEASE
ApiName	string	API 名称	获取关键词二维码地址
RequestConfig	object	由 RequestConfig 组成的格式，返回 API 前端定义信息
RequestPath	string	API path，比如 API 的完全地址为`http://api.a.com：8080/object/add?key1=value1&key2=value2`，path 是指`/object/add`这一部分。	/api/billing/test/[type]
RequestHttpMethod	string	HTTP Method，取值为：GET、POST、DELETE、PUT、HEADER、TRACE、PATCH、CONNECT、OPTIONS。	POST
BodyFormat	string	当 RequestMode 值为 MAPPING 时有效。 POST/PUT 请求时，表示数据以何种方式传递给服务器，取值为：FORM、STREAM，分别表示表单形式(k-v 对应)、字节流形式。	STREAM
RequestMode	string	入参请求的模式，取值为： MAPPING：入参映射（过滤未知参数） PASSTHROUGH：入参透传 MAPPING_PASSTHROUGH：入参映射（透传未知参数）	MAPPING
PostBodyDescription	string	Body 描述	fwefwef
RequestProtocol	string	API 支持的协议类型，可以多选，多选情况下以英文逗号隔开，如：”HTTP,HTTPS”，取值为：HTTP、HTTPS。	HTTP
EscapePathParam	boolean	是否转义 Path 参数，如果为 true，则 Path 上的[param]将被视为普通字符。	true
ErrorCodeSamples	object
ErrorCodeSample	array<object>	后端服务返回的错误码示例
	object	后端服务返回的错误码示例
Code	string	错误码	Error
Message	string	错误消息	error message
Description	string	错误码描述	未授权
RequestParameters	object
RequestParameter	array<object>	由 RequestParameter 组成的数组格式，返回 API 中前端入参信息项
	object	由 RequestParameter 组成的数组格式，返回 API 中前端入参信息项
JsonScheme	string	JSON scheme	{}
MaxValue	integer	最大值	200
ArrayItemsType	string	数组元素的类型	String
MinValue	integer	最小值	123456
DocShow	string	文档可见，取值为：PUBLIC、PRIVATE	PUBLIC
MaxLength	integer	最大长度	123456
DefaultValue	string	默认值	20
ApiParameterName	string	API 参数名称	Length
EnumValue	string	当 ParameterType=Int、Long、Float、Double 或 String，允许输入的散列值，不同的值用英文的逗号分隔，形如：1,2,3,4,9 或 A,B,C,E,F。	boy,girl
DemoValue	string	示例值	20
Required	string	是否必填	OPTIONAL
Description	string	描述信息	参数说明
ParameterType	string	参数类型	String
RegularExpression	string	当 ParameterType=String，参数验证（正则表达式）	xxx
MinLength	integer	最小长度	2
DocOrder	integer	文档中顺序	0
Location	string	参数位置，取值为：BODY、HEAD、QUERY、PATH	HEAD

示例

正常返回示例

JSON格式

{
  "ApiId": "b24be7e59a104e52bffbf432cc9272af",
  "ResultType": "JSON",
  "DisableInternet": true,
  "ResultSample": "{\\n  \\\"status\\\": 0,\\n  \\\"data\\\": {\\n    \\\"count\\\": 1,\\n    \\\"list\\\": [\\n      \\\"352\\\"\\n    ]\\n  },\\n  \\\"message\\\": \\\"success\\\"\\n}",
  "RegionId": "cn-hangzhou",
  "ForceNonceCheck": true,
  "Visibility": "PUBLIC",
  "FailResultSample": "{\"errorCode\":\"fail\",\"errorMessage\":\"param invalid\"}",
  "AuthType": "APP",
  "RequestId": "F253FB5F-9AE1-5DDA-99B5-46BE00A3719E",
  "GroupId": "f51d08c5b7c84342905544ebaec26d35",
  "GroupName": "会员时代交易服务",
  "Description": "领克数字商城OMS-UAT",
  "DeployedTime": "2022-07-13T16:00:33Z",
  "StageName": "RELEASE",
  "ApiName": "获取关键词二维码地址",
  "RequestConfig": {
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP",
    "EscapePathParam": true
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "Error",
        "Message": "error message",
        "Description": "未授权"
      }
    ]
  },
  "RequestParameters": {
    "RequestParameter": [
      {
        "JsonScheme": "{}",
        "MaxValue": 200,
        "ArrayItemsType": "String",
        "MinValue": 123456,
        "DocShow": "PUBLIC",
        "MaxLength": 123456,
        "DefaultValue": "20",
        "ApiParameterName": "Length",
        "EnumValue": "boy,girl",
        "DemoValue": "20",
        "Required": "OPTIONAL",
        "Description": "参数说明",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 2,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。