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

[rubenfonseca]

@nlykkei I'm planning to work on this tomorrow if that's ok :)

[nlykkei]

@rubenfonseca Thank you 🎉

Consider Pydantic's Field, it has an attribute called json_schema_extra for providing extra JSON schema properties:

A dict or callable to provide extra JSON schema properties.

https://docs.pydantic.dev/latest/api/fields/

Such customizability is important for injecting e.g. AWS API Gateway specific objects into the generated OpenAPI spec. Furthermore, depending on the securitySchemes and security implementation for OAuth 2.0, this level of customizability will also be required for users to generate other types of OpenAPI security mechanisms, e.g. API key, HTTP Basic, etc.

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 #4036!

I wouldn't think to much about abusing this mechanism, as neither does Pydantic. It's a mean for users to extend Powertools for AWS Lambda OpenAPI generation capabilities.

I'm really sorry that I haven't had more time. I'm an open source developer by heart, thus my current job takes too much of my time

[nlykkei]

Sorry, forgot the link to the documentation!

It shows an example of embedding API Gateway authorizer extension to have API Gateway create a custom Lambda authorizer using the OpenAPI spec

[rubenfonseca]

I think your point of using json_schema_extra is EXCELLENT for this feature! Thank you so much for pointing this out!

[nlykkei]

I'm happy you found it useful! :) I think Pydantic serves as a good reference

[EricOddz]

Hello, is there any news about this issue?

[leandrodamascena]

Hi @EricOddz! Not yet, I'm working on some v3 issues, but I'll try to look into it next Monday, ok?