Redocly / Redocly/redocly-cli

Lint parameter-description incorrectly flag $ref

Open
#659 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

governance p3 Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the parameter-description warning with the provided file.json and the npx @redocly/openapi-cli lint command, including both path-level and global parameters. Trace the lint rule's handling of parameters whose schema uses $ref, then verify that the warning is absent while other parameter-description cases remain reported.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.