Feature request: Mark API operation as `deprecated` for OpenAPI documentation

[tcysin]

Use case

When customizing API operations, I'd like to be able to mark an operation as deprecated (see Operation Object, OAS v3.0.3).

This helps to tell the users that an operation will be, well, deprecated. Here's what it looks like with Petstore example in Swagger Editor:

Solution/User Experience

An extra deprecated boolean parameter with a False default:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.api_gateway import Router

app = APIGatewayRestResolver()

@app.get("/spam", deprecated=True)
def spam(name):
    return {"message": "mmm... tasty"}

@app.get("/eggs")  # deprecated=False by default
def eggs(name):
    return {"message": "cheese"}

router = Router()

@router.get("/ham", deprecated=True)
def ham():
    return {"message": "ham!"}

Acknowledgment

• [x] This feature request meets Powertools for AWS Lambda (Python) Tenets
• [ ] Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

Thanks for your hard work!

[boring-cyborg[bot]]

Thanks for opening your first issue here! We'll come back to you as soon as we can. In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link