Editing API Documentation in CDK - amazon-web-services

Question

In the AWS Documentation for API Gateway, there are ways to edit your API documentation in the console. Working in CDK, I can't find any way to achieve the same thing. The goal is to create the exact same outputs.
Question 1:
See API Gateway documentation in console. This shows how you can edit pretty much everything you need to get nice headings and so on in your swagger / redoc outputs. But I can't find any way of inserting chunks of yaml / json into the doc in cdk.
Question 2:
Is it possible to prevent your exported OAS file from including all of the options methods? I want to automate the process of updating the API docs after cdk deploy, so it should be done as part of the code.
Question 3:
How can you add tags to break your API into logical groupings. Again, this is something that is very useful in standard API documentation, but I can't find the related section in cdk anywhere?
Really, I think AWS could knock up a short petstore example to help us all out. If I get it working, perhaps I'll come back here and post up one of my own with notes.

Answer 1

Question 1 & Question 3:
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
//https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html
new apigateway.CfnDocumentationPart(this, 'GetDocumentationPart', {
location: {
method: 'GET',
path: '/my/path',
type: 'METHOD',
},
properties: `{
"tags": ["example"],
"description": "This is a description of the method."
}`,
restApiId: 'api-id',
});
//https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html
new apigateway.CfnDocumentationVersion(
this,
'DocumentationVersion',
{
documentationVersion: 'generate-version-id',
restApiId: 'api-id',
}
);
Notice that you need to generate a version to publish the documentation changes. For the version value, I'll suggest generating a UUID.
According to the example above, the GET /my/path will be grouped by the "example" tag at a Swagger UI.
Question 2:
No, it is not possible.
I solved it by creating a lambda function listening to the api-gateway deployment event, getting the JSON file from the api-gateway via AWS SDK, parsing it for removing unwanted paths, and storing it in an S3 bucket.