feat(event_handler): add support for externalDocs attribute in OpenAPI schema

[mhindery]

Issue number: #6948

Summary

OpenAPI generation: add support for passing the top-level externalDocs property in the schema generation.

See the field in the spec on https://swagger.io/docs/specification/v3_0/api-general-info/

Changes

A data model for ExternalDocumentation was already present in this repo. It was however not possible to pass it through in the configure_openapi() method, so it could not be specified by users. This PR adds an argument to this method (and similarly to the enable_swagger()) where such an object can be passed.

User experience

After this PR, users can pass in a link to external documentation to be put in the generated OpenAPI spec.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

No, the new argument is an optional one.

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[leandrodamascena]

Hey @mhindery thanks for sending this PR! Can you please fix the error in CI? Just need to remove the extra import.

[leandrodamascena]

We need to fix this as well.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.20%. Comparing base (eaedf5e) to head (29cc623).
Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6945   +/-   ##
========================================
  Coverage    96.20%   96.20%           
========================================
  Files          273      273           
  Lines        12709    12713    +4     
  Branches       949      950    +1     
========================================
+ Hits         12227    12231    +4     
  Misses         377      377           
  Partials       105      105           

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

Thanks for this PR @mhindery! Approved.

[dreamorosi]

Thank you for the contribution and congrats for your first PR merged in this project 🎉 !

Whenever you can, please leave a comment under the original issue so we can assign it to you and track it properly (GitHub doesn't allow us to assign it without you interacting with it first).

Thanks

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!