首页 API 网关 开发指南 API参考指南 API目录 API管理 DescribeApiDoc - 查询API说明文档

DescribeApiDoc - 查询API说明文档

查询指定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:DescribeApiDocRead
  • ApiGateway
    acs:apigateway:*:{#accountId}:*

请求参数

名称类型必填描述示例值
GroupIdstring

指定的分组编号

123
StageNamestring

环境名称,可选值:

  • RELEASE: 线上
  • TEST: 测试

若不传入,则默认为release。

RELEASE
ApiIdstring

指定的API编号

3b81fd160f5645e097cc8855d75a1cf6

返回参数

名称类型描述示例值
object
ApiIdstring

API编号

b24be7e59a104e52bffbf432cc9272af
ResultTypestring

返回类型

JSON
DisableInternetboolean
  • 设置DisableInternettrue, 仅支持内网调用API。
  • 设置DisableInternetfalse, 则不限制调用。创建API时默认为false。
true
ResultSamplestring

返回示例

{\n \"status\": 0,\n \"data\": {\n \"count\": 1,\n \"list\": [\n \"352\"\n ]\n },\n \"message\": \"success\"\n}
RegionIdstring

API分组所在的地域ID

cn-hangzhou
ForceNonceCheckboolean
  • 设置ForceNonceChecktrue, 请求时强制检查X-Ca-Nonce,这个是请求的唯一标识,一般使用UUID来标识。API网关收到这个参数后会校验这个参数的有效性,同样的值,15分内只能被使用一次。可以有效防止API的重放攻击。

  • 设置ForceNonceCheckfalse,则不检查。创建API时默认为false。

true
Visibilitystring

可见性,取值为:PUBLICPRIVATE,分别表示公开、私有

PUBLIC
FailResultSamplestring

后端服务失败返回应答的示例

{"errorCode":"fail","errorMessage":"param invalid"}
AuthTypestring

安全认证方式,取值为:APP、ANONYMOUS,分别表示阿里云APP、匿名

APP
RequestIdstring

请求ID

F253FB5F-9AE1-5DDA-99B5-46BE00A3719E
GroupIdstring

API分组编号

f51d08c5b7c84342905544ebaec26d35
GroupNamestring

API分组名称

会员时代交易服务
Descriptionstring

API描述

领克数字商城OMS-UAT
DeployedTimestring

发布时间

2022-07-13T16:00:33Z
StageNamestring

环境名称,可选值:

  • RELEASE: 线上
  • TEST: 测试
RELEASE
ApiNamestring

API名称

获取关键词二维码地址
RequestConfigobject

由 RequestConfig 组成的格式,返回API前端定义信息

RequestPathstring

API path,比如API的完全地址为http://api.a.com:8080/object/add?key1=value1&key2=value2,path是指/object/add这一部分。

/api/billing/test/[type]
RequestHttpMethodstring

HTTP Method,取值为:GET、POST、DELETE、PUT、HEADER、TRACE、PATCH、CONNECT、OPTIONS。

POST
BodyFormatstring

RequestMode值为MAPPING时有效。

POST/PUT请求时,表示数据以何种方式传递给服务器,取值为:FORMSTREAM,分别表示表单形式(k-v对应)、字节流形式。

STREAM
RequestModestring

入参请求的模式,取值为:

  • MAPPING:入参映射(过滤未知参数)

  • PASSTHROUGH:入参透传

  • MAPPING_PASSTHROUGH:入参映射(透传未知参数)

MAPPING
PostBodyDescriptionstring

Body描述

fwefwef
RequestProtocolstring

API 支持的协议类型,可以多选,多选情况下以英文逗号隔开,如:”HTTP,HTTPS”,取值为:HTTP、HTTPS。

HTTP
ErrorCodeSamplesarray

后端服务返回的错误码示例

object

后端服务返回的错误码示例

Codestring

错误码

Error
Messagestring

错误消息

error message
Descriptionstring

错误码描述

未授权
ResultDescriptionsarray

api的返回说明

object

api的返回说明

Typestring
Keystring
HasChildboolean
Descriptionstring

API描述

Api description
Pidstring
Mandatoryboolean

是否必填。

true
Namestring
Idstring
RequestParametersarray

由 RequestParameter 组成的数组格式,返回API中前端入参信息项

object

由 RequestParameter 组成的数组格式,返回API中前端入参信息项

JsonSchemestring

JSON scheme

{}
MaxValuelong

最大值

200
ArrayItemsTypestring

数组元素的类型

String
MinValuelong

最小值

123456
DocShowstring

文档可见,取值为:PUBLICPRIVATE

PUBLIC
MaxLengthlong

最大长度

123456
DefaultValuestring

默认值

20
ApiParameterNamestring

API 参数名称

Length
EnumValuestring

ParameterType=Int、Long、Float、Double或String,允许输入的散列值,不同的值用英文的逗号分隔,形如:1,2,3,4,9或A,B,C,E,F。

boy,girl
DemoValuestring

示例值

20
Requiredstring

是否必填

OPTIONAL
Descriptionstring

描述信息

参数说明
ParameterTypestring

参数类型

String
RegularExpressionstring

ParameterType=String,参数验证(正则表达式)

xxx
MinLengthlong

最小长度

2
DocOrderinteger

文档中顺序

0
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD

错误码

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

变更历史

变更时间变更内容概要操作
暂无变更历史
阿里云首页 API 网关 相关技术圈