查询 API 服务文档 - API 网关

描述

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

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

请求参数

名称	类型	是否必须	描述
Action	String	是	操作接口名，系统规定参数，取值：DescribeApiDoc
GroupId	String	否	指定的分组编号
ApiId	String	是	指定的API编号
StageName	String	否	环境名称，可选值： RELEASE: 线上 TEST: 测试若不传入，则默认为release。

返回参数

名称	类型	描述
RequestId	String	本次请求编号
RegionId	String	所在的region
GroupId	String	API分组编号
GroupName	String	API分组名称
StageName	String	环境名称，可选值： RELEASE: 线上 TEST: 测试
ApiId	String	API编号
ApiName	String	API名称
Description	String	API描述
Visibility	String	可见性，取值为：PUBLIC、PRIVATE，分别表示公开、私有
AuthType	String	安全认证方式，取值为：APP、ANONYMOUS，分别表示阿里云APP、匿名
ResultType	String	返回类型
ResultSample	String	返回示例
FailResultSample	String	后端服务失败返回应答的示例
ErrorCodeSamples	ErrorCodeSample	后端服务返回的错误码示例，详情见ApiAttributesType.md#ErrorCodeSamples
RequestConfig	RequestConfig	由 RequestConfig 组成的格式，返回API前端定义信息
RequestParameters	RequestParameter	由 RequestParameter 组成的数组格式，返回API中前端入参信息项

示例

请求示例

https://apigateway.cn-qingdao.aliyuncs.com/?Action=DescribeApiDoc
&ApiId=3b81fd160f5645e097cc8855d75a1cf6    
&<公共请求参数>

返回示例

XML格式

<DescribeApiDocResponse>
    <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BZ014</RequestId>
    <RegionId>cn-qingdao</RegionId>
    <GroupId>0009db9c828549768a200320714b8930</GroupId>
    <GroupName>myGroup2</GroupName>
    <StageName>RELEASE</StageName>
    <ApiId>3b81fd160f5645e097cc8855d75a1cf6</ApiId>
    <ApiName>creatobject</ApiName>
    <Description>对象创建</Description>
    <Visibility>public</Visibility>
    <AuthType>APP</AuthType>
    <ResultType>application/json</ResultType>
    <ResultSample></ResultSample>
    <FailResultSample></FailResultSample>
    <ErrorCodeSamples>
        <ErrorCodeSample>
            <Code>400</Code>
            <Message>Missing the parameter UserId</Message>
            <Description>请求缺少参数 UserId</Description>
        </ErrorCodeSample>
    </ErrorCodeSamples>
    <RequestConfig>
        <RequestProtocol>HTTP</RequestProtocol>
        <RequestHttpMethod>GET</RequestHttpMethod>
        <RequestPath>/mypath/creatobject</RequestPath>
        <BodyFormat>FORM</BodyFormat>
        <PostBodyDescription>对象</PostBodyDescription>
    </RequestConfig>        
    <RequestParameters>
        <RequestParameter>
            <ApiParameterName>RequestKey1</ApiParameterName>
            <Location>QUERY</Location>
            <ParameterType>String</ParameterType>
            <Required>REQUIRED</Required>
            <DefaultValue></DefaultValue>
            <DemoValue>demo1</DemoValue>
            <MaxValue></MaxValue>
            <MinValue></MinValue>
            <MaxLength>100</MaxLength>
            <MinLength>3</MinLength>
            <RegularExpression></RegularExpression>
            <JsonScheme></JsonScheme>
            <EnumValue></EnumValue>
            <DocShow>PUBLIC</DocShow>
            <DocOrder>1</DocOrder>
            <Description>Desc1</Description>
        </RequestParameter>
        <RequestParameter>
            <ApiParameterName>RequestKey2</ApiParameterName>
            <Location>QUERY</Location>
            <ParameterType>Number</ParameterType>
            <Required>OPTIONAL</Required>
            <DefaultValue></DefaultValue>
            <DemoValue>12</DemoValue>
            <MaxValue>120</MaxValue>
            <MinValue>100</MinValue>
            <MaxLength></MaxLength>
            <MinLength></MinLength>
            <RegularExpression></RegularExpression>
            <JsonScheme></JsonScheme>
            <EnumValue></EnumValue>
            <DocShow>PUBLIC</DocShow>
            <DocOrder>2</DocOrder>
            <Description>Desc2</Description>
        </RequestParameter>
    </RequestParameters>        
</DescribeApiDocResponse>

JSON格式

{
    "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BZ014",
    "RegionId": "cn-qingdao",
    "GroupId": "0009db9c828549768a200320714b8930",
    "GroupName": "myGroup2",
    "StageName": "RELEASE",
    "ApiId": "3b81fd160f5645e097cc8855d75a1cf6",
    "ApiName": "creatobject",
    "Description": "对象创建",
    "Visibility": "public",
    "AuthType": "APP",
    "ResultType": "application/json",
    "ResultSample": "200",
    "FailResultSample": "400",
    "ErrorCodeSamples": {
        "ErrorCodeSample": [
            {
                "Code": "400",
                "Message": "Missing the parameter UserId",
                "Description": "请求缺少参数 UserId"
            }
        ]
    },
    "RequestConfig": {
      "RequestProtocol": "HTTP",
      "RequestHttpMethod": "GET",
      "RequestPath": "/mypath/creatobject",
      "BodyFormat": "FORM",
      "PostBodyDescription": "对象"
    },
    "RequestParameters": {
      "RequestParameter": [
        {
          "ApiParameterName": "RequestKey1",
          "Location": "QUERY",
          "ParameterType": "String",
          "Required": "REQUIRED",
          "DemoValue": "demo1",
          "MaxLength": "100",
          "MinLength": "3",
          "DocShow": "PUBLIC",
          "DocOrder": "1",
          "Description": "Desc1"
        },
        {
          "ApiParameterName": "RequestKey2",
          "Location": "QUERY",
          "ParameterType": "Number",
          "Required": "OPTIONAL",
          "DemoValue": "12",
          "MaxValue": "120",
          "MinValue": "100",
          "DocShow": "PUBLIC",
          "DocOrder": "2",
          "Description": "Desc2"
        }
      ]
    }
  }