Does x-amazon-apigateway-documentation and documentationParts actually work?

Question

For the life of me, I can't seem to get the `x-amazon-apigateway-documentation` and `documentationParts` to actually do the things they claim to do.

I'm using the following aws cli v2 command to upload my OpenAPI generated documentation: `aws apigateway import-documentation-parts --rest-api-id abc111ccc --body fileb://openAPI.json --mode overwrite`

This will generate the DocumentParts under the Documentation tab of an API Gateway API, but when you come to publish it, it seems to pick and choose and mostly just ignore what you have listed there.

Consider a snippet of an OpenAPI document:

```
{
  "openapi": "3.0.1",
  "info": {
    "title": "PDF Generation",
    "description": "TP Comparison API 0.0.23",
    "version": "1.1.0"
  }
}
```

Here we are just listing the basics of an OpenAPI document, the info section... We then add `x-amazon-apigateway-documentation` and the corresponding documentationPart to the OpenAPI file:

```
{
  "openapi": "3.0.1",
  "info": {
    "title": "PDF Generation",
    "description": "TP Comparison API 0.0.23",
    "version": "1.1.0"
  },
  "x-amazon-apigateway-documentation": {
    "version": "1.2.0",
    "documentationParts": [
      {
        "location": { "type": "API" },
        "properties": {
          "info": {
            "title": "PDF Generation",
            "description": "TP Comparison API 0.0.23",
            "version": "1.1.1"
          }
        }
      }
    ]
  }
}
```

I then run the AWS CLI v2 command to upload the OpenAPI file, and when i go to the corresponding API, I indeed see under the Documentation tab a Type of **API** with properties of  
```
{
  "title": "PDF Generation",
  "description": "TP Comparison API 0.0.23",
  "version": "1.1.0"
}
```
And when I go to Publish the documentation and look at the published documentation as a OpenAPI 3 JSON file, what i get is this:

```
{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "uat-PdfGeneration",
    "description" : "TP Comparison API 0.0.23",
    "version" : "2023-06-23T15:25:54Z"
  },
```

Where has the `title` and `version` come from?  None of those are what I uploaded to AWS... they're in none of my files, but for some reason they're populated in the exported documentation?

So what is going on with `x-amazon-apigateway-documentation` and `documentationParts`?  Is it basically unsupported and a bit of code that was never finished off?  Am I augmenting my OpenAPI file badly?

Answer

Hello,

From the query, I understand that you are importing documentation parts from `openAPI.json` using "import-documentation-parts" command which returns (1) but when you publish the documentation and export it as an OpenAPI 3 JSON file, you observe (2).

* I tried to use the same `openAPI.json` file you shared and imported using the same command. Here I received (3). Now I tried to publish the documentation and export it as an OpenAPI 3 JSON file and observed (4).

* Further, I exported it as OpenAPI 3 + API Gateway Extensions and observed (5). Even with Export as OpenAPI 3 + Postman Extensions, I was able to observe (4)

* From [4], the title is the name of the API Gateway API and the version is the created date/time of the API.
* Similarly in (2) , the title is the name of API "uat-PdfGeneration" and version is the creation date/time of it "2023-06-23T15:25:54Z"

In this scenario, I would like to share with you that when we export using OpenAPI 3 & OpenAPI 3 + Postman Extensions, we will not be able to see the documentationParts for the "type": "API". When we use OpenAPI 3 + API Gateway Extensions, we can see documentationParts for the "type": "API" because we are using API Extensions for the specified location.

You can refer https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-documenting-api.html and go through the all 7 Topics mentioned for better understanding.

(1):

```
{
  "title": "PDF Generation",
  "description": "TP Comparison API 0.0.23",
  "version": "1.1.0"
}
```

(2):

```
{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "uat-PdfGeneration",
    "description" : "TP Comparison API 0.0.23",
    "version" : "2023-06-23T15:25:54Z"
  },
```

(3):

```
{
  "info": {
    "title": "PDF Generation",
    "description": "TP Comparison API 0.0.23",
    "version": "1.1.1"
  }
}
```
(4):

```
{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "xyz",
    "description" : "TP Comparison API 0.0.23",
    "version" : "2023-07-06T09:16:09Z"
  },
```
(5):

```
"x-amazon-apigateway-documentation" : {
    "version" : "12",
    "createdDate" : "2023-07-14T09:53:39Z",
    "documentationParts" : [ {
      "location" : {
        "type" : "API"
      },
      "properties" : {
        "info" : {
          "title" : "PDF Generation",
          "description" : "TP Comparison API 0.0.23",
          "version" : "1.1.1"
        }
      }
    } ]
  }
```

Does x-amazon-apigateway-documentation and documentationParts actually work?

Relevant content