Rule operation-description now requires both a description AND a summary?

[vgadoury-numetrix]

On v0.16.5 (and probably since #475), the operation-description rule fires a warning if an operation object doesn't have a description, even if it has a valid summary.

In fact, it also triggers if the operation contains a valid description, but no summary, saying that "operation [...] is missing a summary".

I'm not sure if behavior is intended or not (it goes contrary to the logic decided in #174), but it doesn't match the rule's description that is linked in the reports:

Checks that an Operation Object contains a description OR a summary and that it meets a minimum number of words.

[daveshanley]

Yeah, this is me being pedantic, what is the point of a linter if you don't put both in? they are used differently by different tools.

It's also a good point for me to update the docs to change that OR to an AND

[vgadoury-numetrix]

I personnaly think that the old rule was better (to warn only if both are missing), but I see your point. By curiosity, is there any listing or examples of things that could go wrong if either is missing? Which tools might require both, or at least a description, or at least a summary?

The main problem I have is that the rule to require BOTH is hardcoded in the go function, so I could not find an easy way to change that behavior from the configurations (but I admit I'm didn't spend much time trying to go deeper than justenabling/disabling pre-built rules). In my case, this reduces the attractiveness of using vacuum for validating internal APIs or as PR requirements.

Maybe there could be three rules instead: operation-description, operation-summary, and operation-description-or-summary? And both operation-description and operation-summary could be enabled by default, to force having both (with minimum length). This way people could configure this behavior to fit their needs and toolset, while by default getting the stronger check and the warning about "if you don't put a description/summary, others might have trouble with you API". I think that would also make the warning message easier to understand for when the summary is missing.

[vgadoury-numetrix]

Or alternatively, maybe just adding a new optional functionOptions to oasDescriptions to configure if it requires one or both of the description and summary would be sufficient to allow rules override.