Skip to content

docs: add openapi docs#7939

Merged
leandrodamascena merged 3 commits intodevelopfrom
fix/app-multiple-spc
Apr 6, 2026
Merged

docs: add openapi docs#7939
leandrodamascena merged 3 commits intodevelopfrom
fix/app-multiple-spc

Conversation

@leandrodamascena
Copy link
Copy Markdown
Contributor

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.

@leandrodamascena leandrodamascena requested a review from a team as a code owner January 9, 2026 16:55
@pull-request-size pull-request-size bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jan 9, 2026
@boring-cyborg boring-cyborg bot added documentation Improvements or additions to documentation event_handlers tests labels Jan 9, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 9, 2026

⚠️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.

3 similar comments
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 9, 2026

⚠️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
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 9, 2026

⚠️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
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 9, 2026

⚠️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
Copy link
Copy Markdown

sonarqubecloud bot commented Jan 9, 2026

@ran-isenberg
Copy link
Copy Markdown
Contributor

ran-isenberg commented Apr 2, 2026

@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
Copy link
Copy Markdown
Contributor

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

@ran-isenberg
Copy link
Copy Markdown
Contributor

@leandrodamascena is it possible to get an update on this? it's a bit stuck since January. seems to be working just fine, with a minor exception hiding issue.

@leandrodamascena
Copy link
Copy Markdown
Contributor Author

leandrodamascena commented Apr 6, 2026

@leandrodamascena is it possible to get an update on this? it's a bit stuck since January. seems to be working just fine, with a minor exception hiding issue.

Hey @ran-isenberg! Thanks for flagging this. I'll include that in the next release - will happen in the next week! I'll also add another great stuff to ease the dependency injection stuff - #8099.

I'll connect on Discord tomorrow to talk more about that with you.

Thanks for always raising the bar here!

leandrodamascena and others added 2 commits April 6, 2026 23:31
@powertools-for-aws-oss-automation powertools-for-aws-oss-automation bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Apr 6, 2026
@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud bot commented Apr 6, 2026

@leandrodamascena leandrodamascena requested a review from hjgraca April 6, 2026 15:46
Copy link
Copy Markdown
Contributor Author

@leandrodamascena leandrodamascena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for validating this @ran-isenberg! This is approved and will be released next week. 🚀

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 6, 2026

Codecov Report

❌ Patch coverage is 85.00000% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.63%. Comparing base (ae16510) to head (da95aec).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines Patch % Lines
...s_lambda_powertools/event_handler/openapi/merge.py 85.00% 10 Missing and 2 partials ⚠️
Additional details and impacted files
@@             Coverage Diff             @@
##           develop    #7939      +/-   ##
===========================================
- Coverage    96.73%   96.63%   -0.11%     
===========================================
  Files          284      284              
  Lines        14036    14105      +69     
  Branches      1140     1162      +22     
===========================================
+ Hits         13578    13630      +52     
- Misses         332      345      +13     
- Partials       126      130       +4     

☔ 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 leandrodamascena merged commit 5374efb into develop Apr 6, 2026
17 of 19 checks passed
@leandrodamascena leandrodamascena deleted the fix/app-multiple-spc branch April 6, 2026 15:50
@ran-isenberg
Copy link
Copy Markdown
Contributor

its merged!! whoohoo! thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation event_handlers size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Refactor OpenAPI documentation

3 participants