Prefer parameter description over schema description

[austinvalle]

Background

Parameters (query, path, headers, etc.), used in data sources and resources, are merged into the root of a generated schema. This follows the same build process as request/response bodies, but each parameter is treated as an individual attribute, rather then an entire object. Parameters are typically primitive types (string, integer, boolean, etc.), whereas request/response bodies are typically an object.

Problem

When building a parameter's schema and mapping into Framework IR, it follows the same process as request/response bodies for determining the Description of an attribute; by looking for the schema level description field. However it is very common for OpenAPI specs to define the description at the parameter level. OAS example below:

"parameters": [
    {
        "name": "petId",
        "in": "path",
        // This is the description we want
        "description": "ID of pet to return",
        "required": true,
        "schema": {
            "type": "integer",
            "format": "int64",
            // This is where the logic is currently looking for description (and if it exists, it will pick it up)
            // "description": "OpenAPI developers and tooling don't commonly use this field for parameters"
        }
    }
]

Solution

When building parameters, we should ensure that the parameter level description is used if it has a value, otherwise, use the schema level description like we are today.

[austinvalle]

Petstore3 example of this: https://github.com/hashicorp/terraform-plugin-codegen-openapi/blob/a74ae9c0b8f4155b9ef5bfa1aceab0f4d193c427/internal/cmd/testdata/petstore3/openapi_spec.json#L303

"parameters": [
    {
        "name": "petId",
        "in": "path",
        "description": "ID of pet to return",
        "required": true,
        "schema": {
            "type": "integer",
            "format": "int64"
        }
    }
]

Scaleway is an example of actually filling out both descriptions ❤️ : https://github.com/hashicorp/terraform-plugin-codegen-openapi/blob/a74ae9c0b8f4155b9ef5bfa1aceab0f4d193c427/internal/cmd/testdata/scaleway/openapi_spec.yml#L5356

parameters:
- in: path
  name: zone
  description: The zone you want to target
  required: true
  schema:
    type: string
    description: The zone you want to target
    enum:
    - fr-par-1
    - fr-par-2
    - fr-par-3
    - nl-ams-1
    - nl-ams-2
    - pl-waw-1
    - pl-waw-2

[github-actions[bot]]

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.