REST API: Provide a way to add extra JSON to generated OpenAPI schema endpoints

[nlykkei]

Use case

It would be helpful, if you would support adding extra JSON to generated OpenAPI schema endpoints.

We would like to use the generated OpenAPI scheme to provision an AWS API Gateway REST API using a OpenAPI 3.0 spec. For this, we need to add e.g. x-amazon-apigateway-integration objects.

The only way to accomplish this is by mutating the generated API spec using a post-processing?

https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/#customizing-api-operations

Example:

  /presigned_put_url:
    get:
      tags:
        - client support
      operationId: getPresignedPutUrl
      description: returns a url for uploading files to the bff backend
      parameters:
        - in: query
          name: file_name
          description: Name of the destination file
          example: my_file.txt
          schema:
            type: string
      responses:
        <<: *default-responses
        "200":
          description: 200 New content - returned when new content available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PutUrlResponse"
      x-amazon-apigateway-integration:
        <<: *apigw-integration-201
        uri: arn:aws:apigateway:${region}:lambda:path/2015-03-31/functions/${presigned_put_arn}/invocations
      security: *oidc-security

Solution/User Experience

I would like to add extra JSON at the endpoint level, using e.g. extra_json, to embed custom AWS API Gateway objects, where they are used

Alternative solutions

I could manipulate the generated OpenAPI spec myself using post-processing

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

[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

[leandrodamascena]

Hello @rubenfonseca! I would like to hear your opinion here.
To me, it makes some sense we inject some additional JSON/keys into the OpenAPI specification, but I'm not sure if we are breaking the OpenAPI contract and may have additional problems with this.

[rubenfonseca]

@leandrodamascena Yes, you can add custom keys prefixed with "x-" in an OpenAPI schema while still maintaining its validity. These keys, also known as "vendor extensions," allow you to include additional metadata or vendor-specific information in the schema without violating the OpenAPI specification.

The OpenAPI specification allows for the use of vendor extensions, which are properties that begin with the prefix "x-". These extensions can be added at various levels of the schema, such as the root level, object definitions, operation objects, and more. So this would break anything.

It's a nice feature that is heavily explorer by @aws/pdk for instance

[rubenfonseca]

@nlykkei I was thinking adding a new optional parameter to all the HTTP method annotations, for instance:

@app.get("/hello", vendor_extensions={...}), where vendor_extensions is of type Optional[dict[str, Any]]

Question: does this make sense to you?

I'm also considering what levels should this be added to. Documentation says:

Extensions are supported on the root level of the API spec and in the following places:

• info section
• paths section, individual paths and operations
• operation parameters
• responses
• tags
• security schemes

Following the same approach, we could add a vendor_extensions optional field to all those places.

[nlykkei]

Thank you, Ruben.

I'm also considering what levels should this be added to. Documentation says:

Which documentation are you referring to?

Yes, it would sense to add vendor_extensions to those places, so users can inject custom JSON into the generated spec, like the x-amazon-apigateway-integrationobject above.

It could also be used to inject other means of authentication, like API key, HTTP Basic, etc. OAuth 2.0 doesn't cover all use cases :)

[rubenfonseca]

Sorry, forgot the link to the documentation!

I would prefer not to abuse this mechanism to just add random things to the schema :P For security specifically, please see the plan I shared in the other thread!

If you want to take 1 (or more) of this tasks, please let me know :D otherwise I'll be happy to help