Add multiline support for docs-description

[paul-barton]

Currently it appears that any multiline description throws a warning with "\\.$".spectral(docs-description).

Documentation tools use description to provide more context to users of the API who are not as familiar with the concepts as the API designers are.

This is an enhancement request to add multiline support for docs-description rule.

Context

Update docs-description to allow multiline descriptions without warnings.

description: |-
  Simply validate the first line for docs-description.

  We have more stuff to describe.

  Multiline support would be great.

Current Behavior

The following throws a warning with "\\.$".spectral(docs-description):

Documentation tools use description to provide more context to users of the API who are not as familiar with the concepts as the API designers are.

description: |-
  Simply validate the first line for docs-description.

  We have more stuff to describe.

  Multiline support would be great.

Expected Behavior

Multiline descriptions have no warnings and only first line checks that the first character is an upper case letter and ends with a period, ignoring indentation used. With support for all YAML Multiline Block Scalars

Possible Solution(s)

Maybe update regex pattern to use ^(([|>]{1})([-+]?)([1-9]?)\n+ {1,9})?([A-Z].*\.)(\n(?:.|\n)*)?$ for checking first character is upper case and ends with a period on the first line, ignoring indentation used.

Regex	Description	Values
Match 0	description	|-2 Simply validate the first line for docs-description. We have more stuff to describe. Multiline support would be great.
Group 1	yaml block scalar header	|-2
Group 2	yaml block scalar style	|
Group 3	yaml block chomping	-
Group 4	yaml indentation indictator	2
Group 5	first line of description	Simply validate the first line for docs-description.
Group 6	remaining description	We have more stuff to describe. Multiline support would be great.

Tested working in custom rule:

  ## Descriptions
  multiline-docs-description:
    description:
      Documentation tools use description to provide more context to users
      of the API who are not as familiar with the concepts as the API designers are.
    given:
      - "#Description_Objects"
    severity: warn
    then:
      - field: description
        function: truthy
      - field: description
        function: length
        functionOptions:
          min: 20
      - field: description
        function: pattern
        functionOptions:
          match: "^(([|>]{1})([-+]?)([1-9]?)\\n+ {1,9})?([A-Z].*\\.)(\\n(?:.|\\n)*)?$"
    message:
      Description must be greater than 20 characters, first character must be upper case, and the
      description must end with a period on the first line, ignoring indentation used.

[jjwedemyer]

I've noticed the same issue in a project.

[alexvoedi]

The problem with this approach is that, according to the OpenAPI specification, CommonMark or Markdown is valid in descriptions. This means that pretty much any restriction to the format of the text causes problems in certain exceptional cases, for example if the text does not end with a period but with a Markdown table.

See the OpenAPI Spec for more information about this.

It would probably be best not to check the structure of the text.

[mnaumanali94]

I agree. We can make a fix for this. Why is is the first line should end with a period rather than the full description ending with a period? @paul-barton