How to associate a RequestBody Documentation Part with a Method Documentation Part?
0
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
{ "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" } } ] } }
Language
English
asked 10 months ago368 viewslg...
1 Answer
- Newest
- Most votes
- Most comments
Are these answers helpful? Upvote the correct answer to help the community benefit from your knowledge.
0
Can you check 2 things?
- 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.
- 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.
answered 10 months agolg...
Relevant content
- asked 5 months agolg...
- asked 2 years agolg...
- asked 10 months agolg...
- asked 5 months agolg...
- AWS OFFICIALUpdated 3 years ago
- AWS OFFICIALUpdated a year ago
- AWS OFFICIALUpdated a year ago
The REST API is deployed and I have now just set the version to 1.1.0, but I'm still not getting an associated RequestBody. I'm going to edit the above to include the whole openAPI file I am uploading via
aws apigateway import-documentation-parts