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

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

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

[anafalcao]

Hi @tcysin ! Thanks for opening this feature request, and sorry for the delay, we were at re:invent last week.
Would you like to open a PR with your solution or do you prefer us to work on it and come back to you?

[tcysin]

It's all good 👍
Yeah, I'm giving it a try.