Add support for common parameters defined on an OAS path item

austinvalle commented 6 months ago

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 #114 by @randomswdev

Code of Conduct

[X] I agree to follow this project's Code of Conduct

austinvalle commented 6 months ago

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 commented 6 months ago

v0.3.0 released 🥳

github-actions[bot] commented 1 month ago

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.

hashicorp / terraform-plugin-codegen-openapi