feat(openapi): add support for micro Lambda pattern

[leandrodamascena]

Issue number: closes #7919

Original Disucssion: #5914

Documentation will come in a separate PR. I'm refactoring the OpenAPI docs.

Summary

This PR adds support for generating unified OpenAPI schemas from multiple Lambda handlers.

This is an old desire from customers that don't use Fat Lambda architecture. When you have micro-functions (one Lambda per route), each Lambda has its own resolver and generates its own OpenAPI spec. This feature allows merging all specs into a single unified schema.

Implementation and security concerns

Some customers suggested a CLI approach, but that could introduce security concerns with arbitrary code execution.

This is pure Python with the customer in control of paths, patterns, and exclusions. Discovery uses AST analysis to detect resolver instances - no code is executed during discovery, just static analysis. The actual schema generation only happens when the customer explicitly calls get_openapi_schema().

Changes

New OpenAPIMerge class and configure_openapi_merge() method to discover and merge OpenAPI schemas from multiple Lambda function handlers into a single specification.

1. OpenAPIMerge class - Standalone class to generate the schema file via Python code. Write a simple script, run it, get your openapi.json.

2. configure_openapi_merge() method - For customers who want a dedicated Lambda to serve the OpenAPI spec and Swagger UI. This Lambda only serves the merged schema - it won't execute the actual route handlers since each route lives in its own Lambda function. The routes in the schema point to API Gateway, which routes to the correct Lambda.

Conflict handling

When the same path+method exists in multiple handlers, use on_conflict:

• warn (default): logs warning, keeps first
• error: raises OpenAPIMergeError
• first: silently keeps first
• last: uses last (override)

Files are sorted alphabetically, so precedence is deterministic.

Supported resolvers

All of them: APIGatewayRestResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, VPCLatticeResolver, VPCLatticeV2Resolver, BedrockAgentResolver.

User experience

Standalone

from aws_lambda_powertools.event_handler.openapi import OpenAPIMerge

merge = OpenAPIMerge(title="My API", version="1.0.0")
merge.discover(path="./functions", pattern="handler.py", recursive=True)

with open("openapi.json", "w") as f:
    f.write(merge.get_openapi_json_schema())

Via resolver (runtime, Swagger UI)

from aws_lambda_powertools.event_handler import APIGatewayRestResolver

app = APIGatewayRestResolver()
app.configure_openapi_merge(
    path="./functions",
    pattern="handler.py",
    recursive=True,
    title="My API",
    version="1.0.0",
)
app.enable_swagger(path="/docs")

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.

[codecov]

Codecov Report

❌ Patch coverage is 94.47236% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.70%. Comparing base (139107a) to head (3d2cb7f).

Files with missing lines	Patch %	Lines
...s_lambda_powertools/event_handler/openapi/merge.py	93.75%	3 Missing and 8 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7920      +/-   ##
===========================================
- Coverage    96.72%   96.70%   -0.02%     
===========================================
  Files          275      277       +2     
  Lines        13214    13411     +197     
  Branches      1006     1054      +48     
===========================================
+ Hits         12781    12969     +188     
- Misses         325      327       +2     
- Partials       108      115       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leandrodamascena]

Hey @dreamorosi and @svozza I'd like a review here. Pls read the PR body before the review.

I'm still fixing some coverage issues.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[ran-isenberg]

yes, this is so overdue!!!! Thank you!

[dreamorosi]

Agree with the approach suggested of having a runtime implementation over a CLI or similar.

I'll leave the technical review of the PR to Stefano - if you want a second pair of eyes you can also involve @sdangol since he's been working on Event Handler as well.

[svozza]

Is this validation sufficient? Don't these paths have other properties we might want to validate?

[leandrodamascena]

Good point, but this is already tested in a bunch of other places, like here and in other methods that uses the swagger.
I think we are safe testing only these props.

[svozza]

Ah, sorry I missed that bit below!