Feature request: openAPI - support for top level tags metadata

[MCR2019]

Expected Behaviour

tag objects should support optional metadata such as description and externalDocs as in the openAPI spec: OAS

(just adding the description would be great)

Current Behaviour

Currently only the required tag name is supported.

Code snippet

from aws_lambda_powertools.event_handler import APIGatewayRestResolver

app = APIGatewayRestResolver(enable_validation=True)


@app.put(
    "/example-resource",
    tags=["Example Tag"]
)
def put():
    pass


if __name__ == "__main__":
    print(app.get_openapi_json_schema(
        tags=["Example Tag"]
    ))

Possible Solution

No response

Steps to Reproduce

• Create an operation and specify a tag.
• There is no way to specify anything other than the tag name

Powertools for AWS Lambda (Python) version

2.30.2

AWS Lambda function runtime

3.10

Packaging format used

PyPi

Debugging logs

No response

[rubenfonseca]

Looking at this now

[leandrodamascena]

I am classifying this issue as a feature request instead of a bug and assigning it to @rubenfonseca.

[rubenfonseca]

Hi @MCR2019 thank you for opening this issue. It seems our top level OpenAPI object is only supporting strings at the moment.

Please notice that according to the spec, tags in Operations are just lists of strings. The only place where a Tag is an object with additional fields is on the top level OpenAPI object:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.models import ExternalDocumentation, Tag

app = APIGatewayRestResolver(enable_validation=True)


@app.put("/example-resource", tags=["Example Tag"])
def put():
    pass


if __name__ == "__main__":
    print(
        app.get_openapi_json_schema(
            tags=[
                Tag(
                    name="Example",
                    description="This is a description",
                    externalDocs=ExternalDocumentation(url="https://example.org", description="Example website"),
                )
            ]
        )
    )

I'll be working on adding support for this.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under 2.31.0 version!