docs: add openapi docs

[leandrodamascena]

Issue number: closes #7925

Summary

This PR adds new documentation for OpenAPI.

It also fixes a bug detected by @ran-isenberg during testing with the OpenAPI Merge.

Changes

Please provide a summary of what's being changed

User experience

Please share what the user experience looks like before and after this change

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[ran-isenberg]

@leandrodamascena @anafalcao
I can validate that it works see ran-isenberg/aws-lambda-handler-cookbook#1008, but I found a minor issue. Please address it and merge the code, this is a huge tech debt for powertools API generation utility that finally got fixed!
Thanks in advance.

Summary:
The OpenAPIMerge.discover() + get_openapi_schema() flow silently swallows handler loading failures in _load_resolver_with_dependencies (merge.py line 228). When a dependent file fails to load (e.g. due to decorators that validate environment variables at import time), the route decorators never execute, and the resulting schema is empty — no paths, no components — with no warning surfaced to the user.

I hit this in aws-lambda-handler-cookbook, where @init_environment_variables(model=MyHandlerEnvVars) (from aws-lambda-env-modeler) on the lambda_handler function validates required env vars at decoration time. When running OpenAPIMerge outside of a Lambda environment (e.g. in CI for static schema generation), this raises a ValueError that gets caught and silently discarded. The @app.post(...) route on the same file never registers, producing a valid but empty OpenAPI schema.

I worked around this by setting dummy env vars before calling discover()/get_openapi_json_schema(), but ideally the library should either:

• Surface a visible warning (not just logger.warning) when dependent files fail to load
• Raise an error or warn when the final schema contains zero paths after discovery found handler files
• Document that handler modules must be side-effect-free at import time for OpenAPIMerge to work

[ran-isenberg]

see https://ran-isenberg.github.io/aws-lambda-handler-cookbook/swagger/swagger/ for multiple handlers swagger generation, it works :)