Specify how relative URLs in rich text descriptions should be resolved

[aibaars]

For URL valued properties the specification defines that relative URLs must be resolved against the server-url. However, how relative URLs in descriptions are to be resolved is not defined.

I think it would make sense to resolve those against the server-url as well.

[MikeRalphson]

As the markdown might perhaps be being rendered into HTML to make the links useful, do such renderers often provide the ability to specify the base URL?

[aibaars]

I don't know to be honest. I mostly use swagger UI and swagger editor for viewing, and as far as I know swagger does not provide the ability to specify a base url for links in markdown descriptions.

[handrews]

In my attempt to handle this with other URI resolution concerns in PR #3838, @ralfhandl pointed out that CommonMark content is rendered and viewed separately from the source YAML/JSON.

My initial thought was that URIs should still be resolved based on the source document so that all renderings point to the same place, particularly given that descriptions might end up stuffed in places like code documentation comments where there is no clear notion of a base URI.

However, that would be an unusual pre-processing requirement for CommonMark, and even if we want to do it it would not be possible in a patch release.

I think the best option is to note that links are resolved in the rendered context, and to note that authors SHOULD exercise caution with relative links as that context may vary unpredictably. There is probably a security concern to document as unexpected link destinations can cause problems of various sorts.

Any objections?

[handrews]

Merged to both 3.0.4 and 3.1.1 - we'll sync up 3.2.0 once those are ready to ship.