Feature request: Add support for API doc auto-gen (SwaggerUI/OpenAPI Specification) from routes

[gwlester]

Use case

It would be useful to allow the code to self-document the API.

In particular, it would be helpful to be able to:

1. Autogenerate a SwaggerUI
2. Be able to generate (this could be a separate utility) the Swagger definition file of the API to import into the API Gateway

Solution/User Experience

Something like flasgger but for Powertools.

Alternative solutions

No response

Acknowledgment

• This feature request meets Lambda Powertools Tenets
• Should this be considered in other Lambda Powertools languages? i.e. Java, TypeScript

[michaelbrewer]

@gwlester - this was also raised in a discussion thread. It should not be hard to add, but it might increase the overall size of the library.

[michaelbrewer]

Here is an example closer to what Powertools does https://github.com/vincentsarago/lambda-proxy

[gwlester]

Maybe this should be in a "sister" library to powertool with powertools providing only a stub implementation?

That way the library size would be kept down.

[michaelbrewer]

I have to assume that a modular version of powertools will happen. then api gw handler would just be a small library additional to the core powertools.

[gwlester]

Modular would be nice.

[heitorlessa]

Hi @gwlester thank you for taking the time to create this feature request. I'd like to ask you a few questions to better understand it.

• Would this be at runtime (/swagger, /redoc) or during development? If the latter, could you update the issue to share your thoughts on what the experience would look like?
• Would that be a replacement for what Amazon API Gateway export provides you?
  • If not a replacement, what are your thoughts on ensuring accuracy beyond view routes? e.g authorization, validation, infra decoupling, etc.
  • If it's a replacement, what are your thoughts on mechanisms to prevent unauthorized access?

• Do you see this starting as a spec generation and eventually expanding to other areas covered by flasgger e.g., validation, from_dict, YAML, HTML sanitization, extending schema, code generation (create API from spec), etc.?
• If you were to create an external library, what information would you need us to provide to ease your maintenance?

Also thank you for sharing about flasgger, I wasn't familiar and I will read more about it.

Thanks!

[gwlester]

@heitorlessa ,

This came up when onboarding a new whose previous experience was with Flask. The person asked how to do this with Powertools -- and it seemed like a missing feature to so I wrote it up,

I've actually not thought about the questions you bring up.

[heitorlessa]

thanks for the additional background @gwlester :) I suspected it was the case but didn't want to assume anything. I've added it to our Ideas backlog so we can explore those answers as we hear more from customers.

As of now, we try to separate what API GW/AppSync offers natively vs what you can do better at runtime. This helps with operational excellence along with common security concerns in the long term. That being said, we'll continuously hear from customers on what bridges need to be built to make that transition easier - sometimes it's code, a separate lib, or documentation with a more opinionated guide (e.g., coming from Flask? coming from Django? etc.)

These lines might blur a bit more as soon as we add official support for Lambda Function URL, along with middleware support for Event Handler to ease common concerns with Function URL.

Thanks!

[kmcquade]

@heitorlessa - I'd also love to have a way to get Swagger docs automatically from Powertools. It's one of the downsides of Powertools - I absolutely love Powertools compared to FastAPI for example for usage in Lambda functions, but FastAPI automatically generates Swagger docs. See example: https://fastapi.tiangolo.com/#interactive-api-docs

Some brainstorming:

In the case of FastAPI, they use Pydantic to control API inputs and it's pretty strongly enforced. Perhaps Powertools could generate Swagger docs from a few data sources. Basically one would need (1) Routes, (2) Parameters and optionally a Request Example, (3) HTTP errors, and (4) Response Data.

1. Routes - all the get/post/put/delete routes from APIGatewayHttpResolver or APIGatewayRestResolver
2. Parameters Use JSON Schemas of models to generate the OpenAPI generated schema, taking inspiration from FastAPI here. Let's say that the user is supplying their JSONSchema to the Powertools schema validator.
3. HTTP errors: This could be based on the Powertools HTTP Errors
4. Response Data: Either the typical Response class or the usage of Powertools Fine grained responses

Caveat: I don't know how to do this myself so I'm really just brainstorming here. Just wanted to provide some ideas that would make sense to me as a developer using this library - do with it what you will.

With that being said, the operational and security advantage that this would give customers would be incredibly useful. I know it would require developers to adjust their code and ascribe to certain conventions to take advantage of these features... but the effort in doing so would have huge payoffs so I think developers would be willing to do it (I certainly would be willing to!).

Hope this helps. Thanks again for such an amazing framework.