aws-powertools/powertools-lambda-python

Tech debt: Improve documentation of Event model fields in VPC Lattice parser Models

Closed this issue · 2 comments

leandrodamascena commented

Description

Enhance the VPC Lattice parser models with field descriptions and examples using Pydantic's Field() functionality. This improvement will provide better documentation and metadata for VPC Lattice event parsing, following the pattern established in PR #7100.

Motivation

Currently, the VPC Lattice models lack detailed field documentation, making it harder for developers to:

  • Understand field purposes without referencing external AWS documentation
  • Generate rich API documentation with tools like Swagger/OpenAPI
  • Create realistic test data using model factories
  • Get helpful IntelliSense in IDEs

Proposed Changes

Add description and examples parameters to all fields in the following models using Field():

Files to modify:

  • aws_lambda_powertools/utilities/parser/models/vpc_lattice.py
  • aws_lambda_powertools/utilities/parser/models/vpc_latticev2.py

Reference events:
Check the sample events in tests/events/ for realistic field values:

  • vpcLatticeEvent.json
  • vpcLatticeEventV2.json

Implementation Requirements

  • ✅ Add detailed description for each field explaining its purpose and usage
  • ✅ Include practical examples showing realistic AWS VPC Lattice values
  • ✅ Base descriptions on official AWS VPC Lattice documentation
  • ✅ Maintain all existing functionality, types, and validation logic
  • ✅ Follow the same pattern established in EventBridge, Kinesis, and ALB models

Example Implementation

# Before
class VpcLatticeRequestContext(BaseModel):
    service_arn: str
    service_network_arn: str
    target_group_arn: str

# After  
class VpcLatticeRequestContext(BaseModel):
    service_arn: str = Field(
        description="The ARN of the VPC Lattice service that processed the request.",
        examples=[
            "arn:aws:vpc-lattice:us-east-1:123456789012:service/svc-12345678901234567",
            "arn:aws:vpc-lattice:eu-west-1:123456789012:service/svc-abcdef1234567890"
        ]
    )
    service_network_arn: str = Field(
        description="The ARN of the VPC Lattice service network.",
        examples=[
            "arn:aws:vpc-lattice:us-east-1:123456789012:servicenetwork/sn-12345678901234567",
            "arn:aws:vpc-lattice:eu-west-1:123456789012:servicenetwork/sn-abcdef1234567890"
        ]
    )
    target_group_arn: str = Field(
        description="The ARN of the target group that received the request.",
        examples=[
            "arn:aws:vpc-lattice:us-east-1:123456789012:targetgroup/tg-12345678901234567",
            "arn:aws:vpc-lattice:eu-west-1:123456789012:targetgroup/tg-abcdef1234567890"
        ]
    )

Benefits

For Developers

  • Better IntelliSense with field descriptions and example values
  • Self-documenting code without needing external AWS documentation
  • Faster development with immediate reference for acceptable values

For Documentation Tools

  • Rich Swagger/OpenAPI docs via .model_json_schema()
  • Automated documentation generation with comprehensive metadata
  • Interactive documentation with practical examples

Getting Started

This is a great first issue for newcomers to Powertools for AWS! The task is straightforward and helps you get familiar with our codebase structure.

Need help?

We're here to support you! Feel free to:

  • Ask questions in the comments
  • Request guidance on implementation approach

Acknowledgment

powertools-for-aws-oss-automation commented

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

github-actions commented

This is now released under 3.20.0 version!