Lint parameter-description incorrectly flag $ref

[Herrick19]

Describe the bug Lint incorrectly trigger an error of type "parameter-description" when a parameter doesn't include a description when a schema is used. Since the schema does contain a description, I believe this is undesirable. Redoc documentation shows the descriptions correctly as (the one from the schema reference)

To Reproduce Steps to reproduce the behavior: just run npx @redocly/openapi-cli lint file.json when the file.json contain a parameter without a description (but pointing to a schema that does have a description)

Expected behavior No error shown .

OpenAPI definition

"/1/object/ezsigntemplatesigner/{pkiEzsigntemplatesignerID}": {
            "description": "",
            "get": {
                "tags": [
                    "Object_Ezsigntemplatesigner"
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ezsigntemplatesigner-getObject-v1-Response"
                                }
                            }
                        },
                        "description": "Successful response"
                    }
                },
                "security": [
                    {
                        "Authorization": []
                    }
                ],
                "operationId": "Ezsigntemplatesigner_GetObject_V1",
                "summary": "Retrieve an existing Ezsigntemplatesigner",
                "description": ""
            },
            "parameters": [
                {
                    "name": "pkiEzsigntemplatesignerID",
                    "schema": {
                        "$ref": "#/components/schemas/Field-pkiEzsigntemplatesignerID"
                    },
                    "in": "path",
                    "required": true
                }
            ]
        },

openapi-cli Version(s) 1.0.0-beta.94

Node.js Version(s) v16.14.2

Additional context To bypass the problem in the example above, I added this:

"description": {
"$ref": "#/components/schemas/Field-pkiEzsigntemplatesignerID/description"
},

It works well for Redoc documentation and for redoc linter, but it causes issues in openapi generator and apicurio so for now I removed this and added exceptions to .redocly.lint-ignore.yaml

Please note the same problem also happens in parameters that are defined globally, not just the ones that are used in paths and operations

[adamaltman]

This isn't a bug. The issue is you are running the recommended ruleset, which includes the parameter-description rule.

You can use a configuration file, redocly.yaml, to turn off any rules (or not use the recommended ruleset).

redocly.yaml

lint:
  extends:
    - recommended
  rules:
    parameter-description: off

[Herrick19]

Hi,

I already know how to turn it off, but I still think it's a "bug" or "improvement" that would benefit from being addressed. Here is why I think this. Consider the following snippet:

    "parameters": {
          "AcceptLanguage": {
              "name": "Accept-Language",
              "schema": {
                  "$ref": "#/components/schemas/Header-Accept-Language"
              },
              "in": "header",
              "required": false
          },
          "sQuery": {
              "name": "sQuery",
              "schema": {
                  "type": "string"
              },
              "in": "query",
              "required": false
          }
      },

Right now, the linter returns an error for both of them.

If I use "parameter-description: off" like you mentionned, the linter won't report any error...

But I would expect the linter to report an error on the second, but not on the first since the first is a reference to a schema that does contain a description...

Hope it make sense

[adamaltman]

I understand what you're saying, but the built-in rules particular perspective is that the parameter has a description, not that the parameter's schema has a description.

This isn't really about the use of the $ref either.

parameters:
  sample:
    name: sample
    in: query
    schema:
       type: string
       description: It's not about this description
    description: It's about this description.

I understand that you are saying that Redoc renders the schema description if the parameter description is not there. The rule enforces some preference in describing APIs though -- in this case, explicitly defining the parameter description.

You may be wanting a flag like:

lint:
  parameter-description:
    severity: error
    allowSchemaDescription: true

[Herrick19]

Ok, yes that would be what is needed then and would allow flexibility.

Let's turn this into a feature request then :)

Thanks a lot.

Regards