Add support for common parameters defined on an OAS path item

[austinvalle]

Use Cases or Problem Statement

Currently, tfplugingen-openapi only detects parameters that are defined in the Operation object (GET method) of an OpenAPI spec. Common parameters for all operations can be defined in the parent Path Item object.

paths:
  /user/{id}:
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
        description: The user ID
    get:
      summary: Gets a user by ID
      ...
    patch:
      summary: Updates an existing user with the specified ID
      ...
    delete:
      summary: Deletes the user with the specified ID
      ...

Proposal

These common parameters defined in path item, should be combined with the existing operation object parameters:

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
        description: The user ID.
    # GET/users/{id}?metadata=true
    get:
      summary: Gets a user by ID
      # Note we only define the query parameter, because the {id} is defined at the path level.
      parameters:
        - in: query
          name: metadata
          schema:
            type: boolean
          required: false
          description: If true, the endpoint returns only the user metadata.
      responses:
        '200':
          description: OK

Note

• We should also support overriding any common parameters with operation level parameters, per the OpenAPI specification:

A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location.

• We also should determine how to handle a query parameter name that has a conflict with a path parameter name. This would be valid in OpenAPI, but would create an invalid Terraform schema with duplicate attributes.

Additional Information

• Original proposal and work in Add support for common parameters for resources and data sources #114 by @randomswdev

Code of Conduct

• I agree to follow this project's Code of Conduct

[austinvalle]

These changes have been merged to main and will be released with v0.3.0 sometime later this week. As always, if you need the changes ASAP you can go install from the latest commit in main

go install github.com/hashicorp/terraform-plugin-codegen-openapi/cmd/tfplugingen-openapi@dfe71df55db5285bcb904e2d6262ff62fd2be3df

[austinvalle]

v0.3.0 released 🥳

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.