edit-icon download-icon

DescribeApiDoc

Last Updated: Dec 18, 2017

Description

For querying descriptive documents of a specified API.

  • This function is intended for API callers. The specified API must be a public API or an authorized private API that is released to the running stage.
  • If you are an API caller, the service information, parameter definition and other details of the API you specify are returned to you.
  • If you are an API activator, you can call the API to view the definition of the specified API running in the specified stage. The definition is the one taking effect in the stage and may be different from the definition of the API you modify.
  • If you are an API activator, you must confirm that the API is a public API or your app has been authorized because authentication on API callers is required.

Request parameters

Name Type Required? Description
Action String Yes Operation interface, which is a required parameter; value: DescribeApiDoc.
GroupId String Yes ID of the specified group.
ApiId String Yes ID of the specified API.
StageName String No Stage name; values:
  • RELEASE: Online
  • TEST: Test
If this parameter is not specified, the default value is release.

Return parameters

Name Type Description
RequestId String ID of the current request.
RegionId String Region where the API is located.
GroupId String API group ID.
GroupName String API group name.
StageName String Stage name; values:
  • RELEASE: Online
  • TEST: Test
ApiId String ID of the API.
ApiName String API name.
Description String API description.
Visibility String Visibility; values: PUBLIC and PRIVATE, indicating a public API and a private API respectively.
AuthType String Security authentication method; values: app and ANONYMOUS, indicating Alibaba Cloud app and anonymous type respectively.
ResultType String Type returned.
ResultSample String Response example.
FailResultSample String Sample of the reply failure returned by the backend service.
ErrorCodeSamples ErrorCodeSample Sample of the error code returned by the backend service. For more information, see ApiAttributesType.md#ErrorCodeSamples.
RequestConfig RequestConfig Returned API front-end definition information, in a format consisting of RequestConfig.
RequestParameters RequestParameter Returned front-end input parameter information items in the API, in an array consisting of RequestParameter.

Examples

Request example

  1. https://apigateway.cn-qingdao.aliyuncs.com/?Action=DescribeApiDoc
  2. &GroupId=0009db9c828549768a200320714b8930
  3. &ApiId=3b81fd160f5645e097cc8855d75a1cf6
  4. &<Public request parameters>

Response example

XML format

  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> Object creation</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> Request where the parameter UserId is missing</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> Object</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 format

  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": " Object creation",
  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": " Request where the parameter UserId is missing"
  21. }
  22. ]
  23. },
  24. "RequestConfig": {
  25. "RequestProtocol": "HTTP",
  26. "RequestHttpMethod": "GET",
  27. "RequestPath": "/mypath/creatobject",
  28. "BodyFormat": "FORM",
  29. " PostBodyDescription" : " Object"
  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. }
Thank you! We've received your feedback.