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 95.67308% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.72%. Comparing base (4602ffc) to head (5b9b37c).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
...s_lambda_powertools/event_handler/openapi/merge.py	95.16%	2 Missing and 7 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7920      +/-   ##
===========================================
- Coverage    96.72%   96.72%   -0.01%     
===========================================
  Files          275      277       +2     
  Lines        13214    13420     +206     
  Branches      1006     1056      +50     
===========================================
+ Hits         12781    12980     +199     
- Misses         325      326       +1     
- Partials       108      114       +6     

☔ 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.

[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.

[Copilot]

Pull request overview

This PR introduces support for generating unified OpenAPI schemas from multiple Lambda handlers, targeting micro-function architectures where each Lambda function has its own resolver. The feature provides two usage patterns: a standalone OpenAPIMerge class for CI/CD pipelines and build-time schema generation, and a configure_openapi_merge() method for serving merged schemas at runtime via a dedicated Lambda with Swagger UI.

Key changes:

• New OpenAPIMerge class with AST-based resolver discovery (no code execution during discovery)
• Conflict resolution strategies (warn, error, first, last) for handling duplicate path+method combinations
• Integration with existing Swagger UI functionality via configure_openapi_merge() method

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
aws_lambda_powertools/event_handler/openapi/merge.py	Core implementation of OpenAPIMerge class with discovery and merging logic
aws_lambda_powertools/event_handler/openapi/exceptions.py	New OpenAPIMergeError exception for conflict handling
aws_lambda_powertools/event_handler/openapi/init.py	Exports OpenAPIMerge and OpenAPIMergeError for public API
aws_lambda_powertools/event_handler/api_gateway.py	Adds configure_openapi_merge() method and integrates with enable_swagger()
tests/unit/event_handler/openapi/test_openapi_merge.py	Unit tests for internal discovery and loading functions
tests/functional/event_handler/_pydantic/test_openapi_merge.py	Functional tests covering discovery, merging, conflict handling, and Swagger integration
tests/functional/event_handler/_pydantic/merge_handlers/*.py	Test handler files demonstrating various resolver types and conflict scenarios

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dreamorosi]

Let's wait for @svozza final review before merging pls

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[leandrodamascena]

This PR is ready to be merged. @ran-isenberg offered to test it today with his Cookbook project - https://github.com/ran-isenberg/aws-lambda-handler-cookbook - and I would take the opportunity to find bugs and everything else before the official release.

That said, @svozza, could you prioritize this review a bit? I would greatly appreciate the help.