How to associate a RequestBody Documentation Part with a Method Documentation Part?

Question

I'm trying to build out a library to augment an openAPI document with `x-amazon-apigateway-documentation`.

I have built out the `documentationParts` like so:

```
"x-amazon-apigateway-documentation": {
    "version": "1.1.0",
    "documentationParts": [
      { "location": { "type": "RESOURCE", "path": "/" }, "properties": {} },
      {
        "location": { "type": "MODEL", "name": "TPComparisonRequest" },
        "properties": {
          "schema": {
            "type": "string"
          }
        }
      },
      {
        "location": { "type": "REQUEST_BODY", "path": "/", "method": "post" },
        "properties": {
          "description": "An application/json body data about the Training Providers."
        }
      },
      {
        "location": {
          "type": "METHOD",
          "path": "/",
          "method": "post"
        },
        "properties": {
          "summary": "Sends an email to the user",
          "description": "Sends an email to the user with a PDF",
          "requestModels": { "application/json": "TPComparisonRequest" }
        }
      }
    ]
```

But when I go to export the documentation from the API Gateway console as openAPI, the generated openAPI does not contain any requestBody, e.g.

```
{
  "openapi" : "3.0.1",
  "paths" : {
    "/" : {
      "post" : {
        "summary" : "Sends an email to the user",
        "description" : "Sends an email to the user with a PDF"
      }
    }
  }
}
```

What am I doing wrong with my `documentationPart` array?

EDIT:

This is the while openAPI file I am uploading via running the AWS CLI v2 command: `aws apigateway import-documentation-parts --rest-api-id my-rest-api-id --body fileb://openAPI.json --mode overwrite`

```json
{
  "openapi": "3.0.1",
  "components": {
    "schemas": {
      "SuccessResponse": { "type": "string" },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "errors": { "type": "object" }
        }
      },
      "TPComparisonRequest": {
        "type": "string"
      },
      "StrictTransportSecurity": {
        "type": "string",
        "default": "max-age=31536000; includeSubDomains"
      },
      "ContentSecurityPolicy": {
        "type": "string",
        "default": "default-src 'self'; object-src 'none'; child-src 'self'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
      },
      "ReferrerPolicy": { "type": "string", "default": "no-referrer" },
      "AccessControlAllowOrigin": {
        "type": "string",
        "default": "*",
        "example": "*"
      }
    }
  },
  "info": {
    "title": "PDF Generation",
    "description": "TP Comparison API",
    "version": "1.1.0"
  },
  "paths": {
    "/": {
      "post": {
        "summary": "Sends an email to the user",
        "description": "Sends an email to the user with a PDF of their comparisons of Training Providers",
        "operationId": "PdfGeneration-uat-create",
        "parameters": [],
        "tags": ["PDF Generation"],
        "requestBody": {
          "description": "An application/json body data about the Training Providers.",
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TPComparisonRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            },
            "headers": {
              "Access-Control-Allow-Origin": {
                "description": "The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)",
                "schema": {
                  "$ref": "#/components/schemas/Access-Control-Allow-Origin"
                }
              },
              "Strict-Transport-Security": {
                "description": "The HTTP Strict-Transport-Security response header (often abbreviated as [HSTS](https://developer.mozilla.org/en-US/docs/Glossary/HSTS)) informs browsers that the site should only be accessed using HTTPS, and that any future attempts to access it using HTTP should automatically be converted to HTTPS. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)",
                "schema": {
                  "$ref": "#/components/schemas/Strict-Transport-Security"
                }
              },
              "Content-Security-Policy": {
                "description": "The HTTP Content-Security-Policy response header allows website administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross-site scripting attacks ([Cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting)). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)",
                "schema": {
                  "$ref": "#/components/schemas/Content-Security-Policy"
                }
              },
              "Referrer-Policy": {
                "description": "The Referrer-Policy [HTTP header](https://developer.mozilla.org/en-US/docs/Glossary/HTTP_header) controls how much [referrer information](https://developer.mozilla.org/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns) (sent with the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header) should be included with requests. Aside from the HTTP header, you can [set this policy in HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy#integration_with_html). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)",
                "schema": { "$ref": "#/components/schemas/Referrer-Policy" }
              }
            }
          },
          "400": {
            "description": "An error message",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            },
            "headers": {
              "Access-Control-Allow-Origin": {
                "description": "The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)",
                "schema": {
                  "$ref": "#/components/schemas/Access-Control-Allow-Origin"
                }
              },
              "Strict-Transport-Security": {
                "description": "The HTTP Strict-Transport-Security response header (often abbreviated as [HSTS](https://developer.mozilla.org/en-US/docs/Glossary/HSTS)) informs browsers that the site should only be accessed using HTTPS, and that any future attempts to access it using HTTP should automatically be converted to HTTPS. - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)",
                "schema": {
                  "$ref": "#/components/schemas/Strict-Transport-Security"
                }
              },
              "Content-Security-Policy": {
                "description": "The HTTP Content-Security-Policy response header allows website administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross-site scripting attacks ([Cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting)). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)",
                "schema": {
                  "$ref": "#/components/schemas/Content-Security-Policy"
                }
              },
              "Referrer-Policy": {
                "description": "The Referrer-Policy [HTTP header](https://developer.mozilla.org/en-US/docs/Glossary/HTTP_header) controls how much [referrer information](https://developer.mozilla.org/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns) (sent with the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header) should be included with requests. Aside from the HTTP header, you can [set this policy in HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy#integration_with_html). - [MDN Link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)",
                "schema": { "$ref": "#/components/schemas/Referrer-Policy" }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://{serverURL}/pdf",
      "description": "The base URL",
      "variables": {
        "serverURL": {
          "default": "example.com",
          "description": "The API URL"
        }
      }
    }
  ],
  "externalDocs": {
    "description": "Postman Collection V2",
    "url": "https://docs.example.com/path/pdf-generation-postmanCollection.json"
  },
  "x-amazon-apigateway-documentation": {
    "version": "1.1.0",
    "documentationParts": [
      {
        "location": { "type": "API" },
        "properties": {
          "info": {
            "title": "PDF Generation",
            "description": "TP Comparison API",
            "version": "1.1.0"
          }
        }
      },
      {
        "location": { "type": "MODEL", "name": "SuccessResponse" },
        "properties": { "schema": { "type": "string" } }
      },
      {
        "location": { "type": "MODEL", "name": "ErrorResponse" },
        "properties": {
          "schema": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "errors": { "type": "object" }
            }
          }
        }
      },
      {
        "location": { "type": "MODEL", "name": "TPComparisonRequest" },
        "properties": {
          "schema": {
            "type": "string"
          }
        }
      },
      {
        "location": { "type": "MODEL", "name": "StrictTransportSecurity" },
        "properties": {
          "schema": {
            "type": "string",
            "default": "max-age=31536000; includeSubDomains"
          }
        }
      },
      {
        "location": { "type": "MODEL", "name": "ContentSecurityPolicy" },
        "properties": {
          "schema": {
            "type": "string",
            "default": "default-src 'self'; object-src 'none'; child-src 'self'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content"
          }
        }
      },
      {
        "location": { "type": "MODEL", "name": "ReferrerPolicy" },
        "properties": {
          "schema": { "type": "string", "default": "no-referrer" }
        }
      },
      {
        "location": { "type": "MODEL", "name": "AccessControlAllowOrigin" },
        "properties": {
          "schema": { "type": "string", "default": "*", "example": "*" }
        }
      },
      { "location": { "type": "RESOURCE", "path": "/" }, "properties": {} },
      {
        "location": { "type": "METHOD", "path": "/", "method": "post" },
        "properties": {
          "description": "Sends an email to the user with a PDF of their comparisons of Training Providers",
          "summary": "Sends an email to the user"
        }
      },
      {
        "location": { "type": "REQUEST_BODY", "path": "/", "method": "post" },
        "properties": {
          "description": "An application/json body data about the Training Providers."
        }
      },
      {
        "location": {
          "path": "/",
          "method": "post",
          "statusCode": "200",
          "type": "RESPONSE"
        },
        "properties": { "description": "The successful response" }
      },
      {
        "location": {
          "path": "/",
          "method": "post",
          "statusCode": "400",
          "type": "RESPONSE"
        },
        "properties": { "description": "An error message" }
      }
    ]
  }
}
```

Answer

Can you check 2 things?

1. Check the version of the x-amazon-apigateway-documentation extension: For example, if you are exporting an OpenAPI 3.0.1 definition, make sure you are using version 1.1.0 of the x-amazon-apigateway-documentation extension.
2. Verify that the API Gateway REST API is deployed: If the API Gateway REST API is not deployed, the exported OpenAPI definition may not include the documentation parts.

How to associate a RequestBody Documentation Part with a Method Documentation Part?

Relevanter Inhalt