feat(core): add documentUrl to JS api and cli formatters by dweber019 · Pull Request #2443 · stoplightio/spectral

dweber019 · 2023-03-29T21:54:19Z

Fixes #1488.

Checklist

Tests added / updated
Docs added / updated

Does this PR introduce a breaking change?

Yes
No

Screenshots

All formatters have been updated.

dweber019 · 2023-03-29T21:54:57Z

Should we add the docuemtnUrl type here stoplightio/types#127?

nahteb · 2023-03-30T10:11:37Z

thanks for raising this PR, we've just recently added documentationUrls to our ruleset and would find this really useful 👍

dweber019 · 2023-04-25T16:51:43Z

@magicmatatjahu @smoya @jonaslagoni any update on this?

jonaslagoni · 2023-04-25T18:38:25Z

I dont get why we are assigned tbh. @P0lip this is a core change, while it does change something for the AsyncAPI rules, this is all you 😄

mnaumanali94 · 2023-05-01T14:08:14Z

👋🏼 @dweber019 First of all, I would like to apologize for the delay in responding to your pull request. We appreciate your valuable contribution to the project.

We understand your intention to output the documentation URL as part of the lint process. However it may clutter the output and become repetitive. Additionally, not all organizations utilize the documentation URL, and some prefer using the description field.

With that in mind, we would like to propose a couple of alternative options:

Add the functionality to output the documentationURL behind the --verbose flag. This would make it an opt-in feature, giving users the choice to include the documentation URL in their lint output. The downside to this approach is that it may not cater to organizations that use the description field instead of the documentationURL.
Introduce a new spectral ruleset explain command that displays information for each rule, including severity, documentationURL, and description. This would provide a more comprehensive overview of the rules without cluttering the lint output.
We would love to hear your thoughts on these approaches or any other ideas you might have. Once we have your input, we can work together to make the necessary changes and integrate them into the project.

Thank you once again for your contribution, and we look forward to collaborating with you on this feature.

dweber019 · 2023-05-06T13:28:00Z

Hi @mnaumanali94

Thx for the feedback. I agree with you. It depends on the use case.
How would you imagine this explain command.

Is this a options flag on lint, and if a rule fails more output is generated
or is it a standalone command to basically extract rule information from the rules file without linting?

For our use case, the first one would satisfy our needs and makes IMHO more sense, as the documentation url or description is needed in case of error mostly on CI side, where you don't like to rerun a command to understand the error.

ShelleeNikole · 2023-09-14T17:43:47Z

@dweber019 Thanks you for raising this issue and for your contribution. I have a similar requirement to make use of the documenationUrl property in Javascript.

@mnaumanali94 Any idea if this PR will be accepted and merged anytime soon?

Cheers!

mnaumanali94 · 2024-07-11T10:30:09Z

LGTM!

dweber019 · 2024-07-15T06:13:57Z

@jonaslagoni @smoya could someone of you check this pr. Thanks a lot

jonaslagoni

@jonaslagoni @smoya could someone of you check this pr. Thanks a lot

As mentioned earlier, no need for us to review core changes that affects AsyncAPI rules or outputs of it 🙂

austinmehmet · 2025-03-11T20:10:41Z

Any update on this? Would really appreciate this feature so we can produce better HTML reports that link to our documentation

frankkilcommins · 2025-03-13T16:54:51Z

@dweber019 I've reviewed and this is looking good. I've also resolved the merge conflicts and merged in the latest from origin/develop.

Some of the documentation-url tests are failing. Could you take a look and we can make sure to get this merged and released?

mnaumanali94 · 2025-03-18T14:54:45Z

@dweber019 gentle nudge on this. Would you be able to take a stab at fixing the tests.

frankkilcommins

LGTM

# @stoplight/spectral-formatters [1.5.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-formatters-1.4.3...@stoplight/spectral-formatters-1.5.0) (2025-04-22) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728))

# [6.15.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-cli-6.14.3...@stoplight/spectral-cli-6.15.0) (2025-04-22) ### Bug Fixes * **deps:** bump elliptic from 6.6.0 to 6.6.1 ([#2782](#2782)) ([5ff9602](5ff9602)) * **repo:** replace discord link with forum link ([#2793](#2793)) ([6229442](6229442)) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728)) * **functions:** add or function ([#2798](#2798)) ([d9ef27f](d9ef27f))

# [1.20.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-1.19.5...@stoplight/spectral-core-1.20.0) (2025-04-22) ### Bug Fixes * **deps:** bump elliptic from 6.6.0 to 6.6.1 ([#2782](#2782)) ([5ff9602](5ff9602)) * **deps:** fix yarn lockfile ([e6c3b9d](e6c3b9d)) * **deps:** update spectral-core in cli ([35687cd](35687cd)) * **repo:** replace discord link with forum link ([#2793](#2793)) ([6229442](6229442)) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728)) * **functions:** add or function ([#2798](#2798)) ([d9ef27f](d9ef27f))

stoplight-bot · 2025-04-22T09:36:15Z

🎉 This PR is included in version 1.20.0 🎉

The release is available on @stoplight/spectral-core-1.20.0

Your semantic-release bot 📦🚀

# [1.10.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-functions-1.9.4...@stoplight/spectral-functions-1.10.0) (2025-04-22) ### Bug Fixes * **deps:** bump elliptic from 6.6.0 to 6.6.1 ([#2782](#2782)) ([5ff9602](5ff9602)) * **deps:** fix yarn lockfile ([e6c3b9d](e6c3b9d)) * **deps:** update spectral-core in cli ([35687cd](35687cd)) * **repo:** replace discord link with forum link ([#2793](#2793)) ([6229442](6229442)) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728)) * **functions:** add or function ([#2798](#2798)) ([d9ef27f](d9ef27f))

# [1.22.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-rulesets-1.21.4...@stoplight/spectral-rulesets-1.22.0) (2025-04-22) ### Bug Fixes * **deps:** bump elliptic from 6.6.0 to 6.6.1 ([#2782](#2782)) ([5ff9602](5ff9602)) * **deps:** fix yarn lockfile ([e6c3b9d](e6c3b9d)) * **deps:** update spectral-core in cli ([35687cd](35687cd)) * **repo:** replace discord link with forum link ([#2793](#2793)) ([6229442](6229442)) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728)) * **functions:** add or function ([#2798](#2798)) ([d9ef27f](d9ef27f))

## [1.1.5](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-runtime-1.1.4...@stoplight/spectral-runtime-1.1.5) (2026-04-14) ### Bug Fixes * **cli:** fix bug where output gets truncated when too long ([#2862](#2862)) ([0e6fd33](0e6fd33)) * **cli:** throw error if no file found to lint ([#2778](#2778)) ([3e20072](3e20072)) * **core:** fix security issue of simple-eval package ([#2886](#2886)) ([8120a76](8120a76)) * **core:** respect off severity in intermediate rulesets ([#2890](#2890)) ([5b99b99](5b99b99)) * **deps:** bump elliptic from 6.6.0 to 6.6.1 ([#2782](#2782)) ([5ff9602](5ff9602)) * **deps:** fix yarn lockfile ([e6c3b9d](e6c3b9d)) * **deps:** post lodash update changes for semantic release ([#2942](#2942)) ([bf530dd](bf530dd)) * **deps:** update spectral-core in cli ([35687cd](35687cd)) * **formatters:** Fix rendering of github actions documentationUrl ([#2895](#2895)) ([df27b06](df27b06)) * **formatters:** markdown formatter with invalid-ref crashes spectral ([#2905](#2905)) ([59728e4](59728e4)) * **functions:** export or function ([#2812](#2812)) ([03532a5](03532a5)) * **repo:** release step marking repo as save for git ([#2884](#2884)) ([87147a6](87147a6)) * **repo:** remove acceptance step on release ([#2882](#2882)) ([73496c6](73496c6)) * **repo:** replace discord link with forum link ([#2793](#2793)) ([6229442](6229442)) * **ruleset-migrator:** fix ruleset migrator output when a rule name contains '/' ([#2859](#2859)) ([115d1d0](115d1d0)) * **rulesets:** use uri-reference for openIdConnectUrl ([#2796](#2796)) ([c57eb59](c57eb59)) ### Features * **core:** add documentUrl to JS api and cli formatters ([#2443](#2443)) ([e787728](e787728)) * **core:** allow extending rulesets with aliases ([#2870](#2870)) ([8db9718](8db9718)) * **core:** further adjustments for extending rulesets with aliases ([#2939](#2939)) ([26144bc](26144bc)) * **functions:** add or function ([#2798](#2798)) ([d9ef27f](d9ef27f)) * **repo:** circleci migration to GHA (OP-35885) ([#2867](#2867)) ([884f079](884f079)) * **repo:** npm release workflow as gha ([#2880](#2880)) ([0147d6e](0147d6e)) * **repo:** post develop merge workflow ([#2877](#2877)) ([9420713](9420713)) * **repo:** replace skypack usage with esm cdn ([#2940](#2940)) ([0d6a910](0d6a910))

dweber019 requested review from a team, jonaslagoni, magicmatatjahu and smoya as code owners March 29, 2023 21:54

dweber019 mentioned this pull request Mar 29, 2023

Guidelines URL not in CLI result baloise-incubator/spectral-ruleset#4

Open

jonaslagoni requested a review from P0lip April 25, 2023 18:38

P0lip force-pushed the develop branch 7 times, most recently from dc9d7f4 to 44c40e2 Compare May 23, 2023 22:56

P0lip force-pushed the develop branch 4 times, most recently from 02ec0d4 to 84faec8 Compare June 9, 2023 19:43

P0lip force-pushed the develop branch 3 times, most recently from 9e92f34 to 6d09915 Compare September 20, 2023 18:42

dillan mentioned this pull request Feb 19, 2024

Include documentation URLs for built-in rulesets #2586

Open

P0lip force-pushed the develop branch 2 times, most recently from 1a04f25 to dc90b7a Compare April 4, 2024 13:19

Merge branch 'develop' into feat/expose-documentation-url

f242026

mnaumanali94 previously approved these changes Jul 11, 2024

View reviewed changes

mnaumanali94 added 2 commits August 1, 2024 10:47

Merge branch 'develop' into feat/expose-documentation-url

25660e0

Merge branch 'develop' into feat/expose-documentation-url

5abf66f

mnaumanali94 dismissed their stale review via 5abf66f October 4, 2024 13:36

jonaslagoni previously approved these changes Oct 11, 2024

View reviewed changes

frankkilcommins mentioned this pull request Mar 5, 2025

Hyperlinks in the message #2786

Open

frankkilcommins requested review from frankkilcommins and removed request for ryotrellim March 13, 2025 09:48

Merge branch 'develop' into feat/expose-documentation-url

6d900ff

frankkilcommins dismissed jonaslagoni’s stale review via 6d900ff March 13, 2025 16:42

frankkilcommins and others added 4 commits April 11, 2025 12:35

Merge branch 'develop' into feat/expose-documentation-url

c1b3834

fix(test-harness): strip spectral version from sarif tests

4ad2e2b

chore(test-harness): fix whitespace linting issue

92cbfbd

chore(test-harness): fix whitespace lint issue

cb1ec31

frankkilcommins approved these changes Apr 18, 2025

View reviewed changes

frankkilcommins merged commit e787728 into stoplightio:develop Apr 18, 2025

stoplight-bot added the released label Apr 22, 2025

Uh oh!

Conversation

dweber019 commented Mar 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dweber019 commented Mar 29, 2023

Uh oh!

nahteb commented Mar 30, 2023

Uh oh!

dweber019 commented Apr 25, 2023

Uh oh!

jonaslagoni commented Apr 25, 2023

Uh oh!

mnaumanali94 commented May 1, 2023

Uh oh!

dweber019 commented May 6, 2023

Uh oh!

ShelleeNikole commented Sep 14, 2023

Uh oh!

mnaumanali94 commented Jul 11, 2024

Uh oh!

dweber019 commented Jul 15, 2024

Uh oh!

jonaslagoni left a comment

Choose a reason for hiding this comment

Uh oh!

austinmehmet commented Mar 11, 2025

Uh oh!

frankkilcommins commented Mar 13, 2025

Uh oh!

mnaumanali94 commented Mar 18, 2025

Uh oh!

frankkilcommins left a comment

Choose a reason for hiding this comment

Uh oh!

stoplight-bot commented Apr 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

dweber019 commented Mar 29, 2023 •

edited

Loading