Confusing AwsIntegration configuration

[jedrekdomanski]

I would like to honestly say that it never felt more painful and frustrating than working with AwsIntegration in typescript.
I would like to ask why some of the available options visible on the screen below are in AwsIntegration props directly and some of them go to options. It is very confusing. For instance, you configure HTTP method, Region and Path override in props but Execution role goes to options. Why? It's so confusing. It would make our life easier if all options were literarily mapped from the screen below to either props or options, otherwise it causes a lot of confusion.

Why Path override is called path? It's so confusing because later in the screen you have URL Path Parameters so I find it difficult to figure out which is which.

Why Execution role is called credentialsRole in IntegrationOptions https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.IntegrationOptions.html#credentialsrole

Moving on, we have options property where you can define integrationResponses. Why is it in options and not in props?
To me it would be way easier to work with it if I had the entire screen mapped either to props or options so I can quickly define what I need. For example.

new apigw.AwsIntegration({
      service: 's3',
      httpMethod: 'GET',
      pathOverride: '{bucket}',
      executionRole: 'xxxxx',
      integrationRequest: {...}
      integrationResponses: [...]
  }

Honestly, I had to spend hours googling and searching and even asking on forums to get help. It feel really painful to work with it. And sorry for the criticising tone but I spent hours trying and trying, I felt like I wanted to cry...

I would like to hear your opinion
Of course, I am happy open a Pull Request to make our life easier if we come to an agreement.

[peterwoodworth]

Sorry to hear this was a confusing and frustrating experience,

Taking a look at the code, IntegrationOptions is used in multiple places throughout the module, and are consistent options regardless of the type of integration. The props directly available are the ones unique to AwsIntegration, same with the other types of integrations. That doesn't answer why we didn't just extend IntegrationOptions rather than accepting it as a prop however, I don't have a great answer for you on that. We typically prefer to have all props be on the first level instead of harder to find like this

This is great feedback, and we'd be willing to update our documentation on this topic. However, a full refactor will require deprecation of existing functionality, and a thorough review. Please open a feature request for this linking this discussion if you would like to see this, and then we'll be able to track it. I think it would just be easier to make the docs as clear as possible (please let us know how exactly they could clarify this), and we could absolutely consider renaming the props with unclear names