全部产品
云市场

查询 API 服务文档

更新时间:2019-02-18 10:59:07

描述

查询指定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中前端入参信息项

示例

请求示例

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

返回示例

XML格式

  1. <DescribeApiDocResponse>
  2. <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BZ014</RequestId>
  3. <RegionId>cn-qingdao</RegionId>
  4. <GroupId>0009db9c828549768a200320714b8930</GroupId>
  5. <GroupName>myGroup2</GroupName>
  6. <StageName>RELEASE</StageName>
  7. <ApiId>3b81fd160f5645e097cc8855d75a1cf6</ApiId>
  8. <ApiName>creatobject</ApiName>
  9. <Description>对象创建</Description>
  10. <Visibility>public</Visibility>
  11. <AuthType>APP</AuthType>
  12. <ResultType>application/json</ResultType>
  13. <ResultSample></ResultSample>
  14. <FailResultSample></FailResultSample>
  15. <ErrorCodeSamples>
  16. <ErrorCodeSample>
  17. <Code>400</Code>
  18. <Message>Missing the parameter UserId</Message>
  19. <Description>请求缺少参数 UserId</Description>
  20. </ErrorCodeSample>
  21. </ErrorCodeSamples>
  22. <RequestConfig>
  23. <RequestProtocol>HTTP</RequestProtocol>
  24. <RequestHttpMethod>GET</RequestHttpMethod>
  25. <RequestPath>/mypath/creatobject</RequestPath>
  26. <BodyFormat>FORM</BodyFormat>
  27. <PostBodyDescription>对象</PostBodyDescription>
  28. </RequestConfig>
  29. <RequestParameters>
  30. <RequestParameter>
  31. <ApiParameterName>RequestKey1</ApiParameterName>
  32. <Location>QUERY</Location>
  33. <ParameterType>String</ParameterType>
  34. <Required>REQUIRED</Required>
  35. <DefaultValue></DefaultValue>
  36. <DemoValue>demo1</DemoValue>
  37. <MaxValue></MaxValue>
  38. <MinValue></MinValue>
  39. <MaxLength>100</MaxLength>
  40. <MinLength>3</MinLength>
  41. <RegularExpression></RegularExpression>
  42. <JsonScheme></JsonScheme>
  43. <EnumValue></EnumValue>
  44. <DocShow>PUBLIC</DocShow>
  45. <DocOrder>1</DocOrder>
  46. <Description>Desc1</Description>
  47. </RequestParameter>
  48. <RequestParameter>
  49. <ApiParameterName>RequestKey2</ApiParameterName>
  50. <Location>QUERY</Location>
  51. <ParameterType>Number</ParameterType>
  52. <Required>OPTIONAL</Required>
  53. <DefaultValue></DefaultValue>
  54. <DemoValue>12</DemoValue>
  55. <MaxValue>120</MaxValue>
  56. <MinValue>100</MinValue>
  57. <MaxLength></MaxLength>
  58. <MinLength></MinLength>
  59. <RegularExpression></RegularExpression>
  60. <JsonScheme></JsonScheme>
  61. <EnumValue></EnumValue>
  62. <DocShow>PUBLIC</DocShow>
  63. <DocOrder>2</DocOrder>
  64. <Description>Desc2</Description>
  65. </RequestParameter>
  66. </RequestParameters>
  67. </DescribeApiDocResponse>

JSON格式

  1. {
  2. "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BZ014",
  3. "RegionId": "cn-qingdao",
  4. "GroupId": "0009db9c828549768a200320714b8930",
  5. "GroupName": "myGroup2",
  6. "StageName": "RELEASE",
  7. "ApiId": "3b81fd160f5645e097cc8855d75a1cf6",
  8. "ApiName": "creatobject",
  9. "Description": "对象创建",
  10. "Visibility": "public",
  11. "AuthType": "APP",
  12. "ResultType": "application/json",
  13. "ResultSample": "200",
  14. "FailResultSample": "400",
  15. "ErrorCodeSamples": {
  16. "ErrorCodeSample": [
  17. {
  18. "Code": "400",
  19. "Message": "Missing the parameter UserId",
  20. "Description": "请求缺少参数 UserId"
  21. }
  22. ]
  23. },
  24. "RequestConfig": {
  25. "RequestProtocol": "HTTP",
  26. "RequestHttpMethod": "GET",
  27. "RequestPath": "/mypath/creatobject",
  28. "BodyFormat": "FORM",
  29. "PostBodyDescription": "对象"
  30. },
  31. "RequestParameters": {
  32. "RequestParameter": [
  33. {
  34. "ApiParameterName": "RequestKey1",
  35. "Location": "QUERY",
  36. "ParameterType": "String",
  37. "Required": "REQUIRED",
  38. "DemoValue": "demo1",
  39. "MaxLength": "100",
  40. "MinLength": "3",
  41. "DocShow": "PUBLIC",
  42. "DocOrder": "1",
  43. "Description": "Desc1"
  44. },
  45. {
  46. "ApiParameterName": "RequestKey2",
  47. "Location": "QUERY",
  48. "ParameterType": "Number",
  49. "Required": "OPTIONAL",
  50. "DemoValue": "12",
  51. "MaxValue": "120",
  52. "MinValue": "100",
  53. "DocShow": "PUBLIC",
  54. "DocOrder": "2",
  55. "Description": "Desc2"
  56. }
  57. ]
  58. }
  59. }