context.report(): add new property for external documentation

[jeremyfiel]

Is your feature request related to a problem? Please describe. As an API governance architect, we have a number of design decisions enforced with Redocly rules. While we try to make the rules self-documenting, there are definitely some instances which require a deeper context on the decision.

Describe the solution you'd like I would like a property to include an external link to documentation supporting the design decision of a particular rule so a user of the linter can find reference material for the rule.

{
    "message": <string>,
    "location": Location{},
    "suggest": <string>[],
    "from": Location{},
    "reference": <string><uri-reference>
}

Describe alternatives you've considered I'm currently trying out \n\t formatting in the message body but I would like something more formal.

report({
      message: `this is a message with a reference to external docs\n\treference: https://www.redocly.com`
      })

  1:1  warning  custom-id/some-rule  this is a message with a reference to external docs
        reference: https://www.redocly.com

[Orest-Yastremskyy]

Hi @jeremyfiel,

Thank you for taking the time to share this idea with us.

I have added it to our list of ideas so that our Product Team can evaluate how it fits our roadmap.

We cannot guarantee that it will be approved nor can provide you with any timelines.

[RomanHotsiy]

This is a nice suggestion.

We're quite busy now but we would happily accept a PR