Improve API Gateway documentation

[mee-aa]

Group traits by task (authentication, method/response, integrations,
endpoint and access control) and alphabetize within each group. Add
Validation sub-sections for traits with validators, cross-references
between aws.apigateway and aws.auth authorization traits, and a section
listing public traits from other namespaces that influence API Gateway
OpenAPI generation. Fix dead developer-guide links. In the OpenAPI
guide, expand the Other traits table, demote Cognito and API key
sections under Authorizers, and add a Recommendations section covering
jsonAdd, substitutions, and CloudFormation Fn::Sub patterns.

Background

• What do these changes do?

  Documentation-only cleanup of the public Amazon API Gateway and
  OpenAPI guides. The trait sections in amazon-apigateway.rst were a
  flat alphabetical list with stale links and inconsistent formatting.
  After the recent set of trait additions (endpointConfiguration,
  gatewayResponses, apiTlsPolicy, cognitoUserPoolsScopes), the
  page needed restructuring to make the traits easier to discover and
  to call out validation behavior.

• Why are they important?

  Smithy users converting models to OpenAPI for API Gateway are the
  primary consumers of these pages. Grouping traits by task, listing
  related traits from aws.auth and smithy.api, and documenting
  validators and recommended workarounds (jsonAdd, substitutions,
  CloudFormation Fn::Sub) makes the public docs match the current trait
  surface and reduces support questions.

Testing

• How did you test these changes?

  • Ran the strict Sphinx build (-W -n) from a clean build directory
    on Python 3.12 with Sphinx 9.1; build succeeds with no warnings.
  • Ran ./gradlew build to confirm the wider project still passes.
  • Verified every cross-reference target (:ref: labels) and external
    link resolves.
  • Verified that every documented trait, validator, and OpenAPI
    extension claim matches the current implementation in
    smithy-aws-apigateway-openapi (mappers, security scheme
    converters) and smithy-aws-apigateway-traits (validators).

Links

• No related issue.

---

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.