Provide optional anchor property for single rule definition used by documentationUrl

[jschaefer77]

User story.
As a rule developer, I can define user friendly rule names and additional anchors, so that I can point to specific sections of my existing documentation.

Is your feature request related to a problem?
Our API style guide is stored in a CMS system, which does generate anchors, but not user friendly ones.
So we cannot use the documentationUrl feature, because we have to use currently the ugly generated anchors as rule name.

Describe the solution you'd like
Provide an additional optional property (anchor) for each rule definition. If this anchor is available in the rule definition, append it to the base documentationUrl instead of using the rule name.

Additional context
Relates to https://github.com/stoplightio/studio/issues/445

[P0lip]

Hey!
Thanks for submitting the idea! I appreciate it.

So we cannot use the documentationUrl feature, because we have to use currently the ugly generated anchors as rule name.

If I understand correctly, each rule has a different URL (anchor in this case), right?

In such case, what about providing an ability to override documentationUrl for each rule, similarly to what we do with formats?

[jschaefer77]

Hi @P0lip ,
yes I need at least a different Url for each rule.
With the current spectral version it is already possible to have a different URL for each rule. The documentationUrl will be used as baseUrl and the rule name will be added as anchor. Having a baseUrl is fine for me, but I would like to use another anchor instead of the rule name.

I think there are two possible ways:

1. Override the documentationUrl for each rule as you mentioned.
2. Or providing an additional attribute for each rule. E.g. if available, anchor attribute will be added after the baseUrl instead of the rule name.

I will give you an example:
Url generated by our CMS: http://mydocumenation.com/guidelines#this-is-an-ugly-anchor-generated-by-our-cms
But the rule name should be much shorter: Avoid-Using-Upper-Case

so it can be something like this:

documenationUrl: http://mydocumenation.com/guidelines
rules:
Avoid-Using-Upper-Case:
anchor: this-is-an-ugly-anchor-generated-by-our-cms
OR
documenationUrl: http://mydocumenation.com/guidelines#this-is-an-ugly-anchor-generated-by-our-cms

What about providing an additional attribute for each rule (e.g. anchor or documenationUrl) and depending on the value (is it a relative or absolute path) it will be added the base documentationUrl (in case of relative) or used as its own documentationUrl (in case of absolute)?

What do you think?

[P0lip]

I'm okay with the first option, namely "Override the documentationUrl for each rule as you mentioned.".
I believe this gives the most flexibility.
Sounds good?

[jschaefer77]

Hi @P0lip, yes that sounds really good. I agree, this will give the most flexibility,

[jschaefer77]

hi @P0lip, thanks a lot for providing the new feature. Appreciate it very much. Do you know, when this will be available in Stoplight Studio Desktop?