Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
jeremyfiel opened this issue Apr 17, 2023 · 2 comments · May be fixed by #1904
Open

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

jeremyfiel opened this issue Apr 17, 2023 · 2 comments · May be fixed by #1904
Labels
help wanted Extra attention is needed p2 Type: Enhancement

Comments

@jeremyfiel
Copy link
Contributor

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
Copy link

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 RomanHotsiy added p2 Type: Enhancement help wanted Extra attention is needed and removed Type: Idea labels May 5, 2023
@RomanHotsiy
Copy link
Member

This is a nice suggestion.

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

@jeremyfiel jeremyfiel mentioned this issue Oct 18, 2023
Open
ImBIOS added a commit to ImBIOS/redocly-cli that referenced this issue Feb 13, 2025
@ImBIOS
Add reference property to context.report() for external documentation
cb15c26 
Add the `reference` property to the `context.report()` method for external documentation links.

Fix Redocly#1052

* **Documentation**: Update `docs/custom-plugins/custom-rules.md` to include the `reference` property in the `context.report()` method documentation.
* **New Rule**: Add `packages/core/src/rules/arazzo/reference-property.ts` to implement a new rule for validating the `reference` property in the report object.
* **Rule Integration**: Modify `packages/core/src/rules/arazzo/index.ts` to import and add the new `reference-property` rule to the existing rules.
* **Unit Tests**: Add `packages/core/src/rules/arazzo/__tests__/reference-property.test.ts` to test the presence and format validation of the `reference` property and error reporting for missing or incorrect `reference` property.
@ImBIOS ImBIOS linked a pull request Feb 13, 2025 that will close this issue
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted Extra attention is needed p2 Type: Enhancement
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add reference property to context.report() for external documentation ImBIOS/redocly-cli
3 participants
@RomanHotsiy @jeremyfiel @Orest-Yastremskyy