Snippet Link Validation Does Not Allow Use of Custom LinkExtractor

[romeara]

Currently, if links are marked as required, but are not formatted as HAL links, documentation generation will fail on the ResponseSnippet validation step. Spring REST docs itself allows providing a specific link extractor to handle different response formats. In the case which this was encountered for, the APIs in question are returning links in a specific format due to constraints outside my control, so aside from the compatibility and workload issues, converting to the more standard response style isn't an option, which is why for the standard REST doc operations we are providing a custom link extractor.

The issue specifically is in DescriptorValidator.LinksSnippetWrapper, which is currently hard-coded to use HypermediaDocumentation.halLinks(). Ideally, this would be an overridable default.

My suggestion to resolve this would be to add a linkExtractor field to ResourceSnippetParameters (and its builder) which defaults to HypermediaDocumentation.halLinks(), and is passed in as a parameter to the DescriptorValidator operation.

[ozscheyge]

Hey @romeara ,

thanks for pointing this out! Looks like, we didn't have a use-case to divert from halLinks(), yet!

Would you be interested in providing a PR?

[romeara]

Hey!

Unfortunately I do not have any Kotlin experience (and more importantly, any Kotlin tooling setup on my system to develop, build and test), otherwise I would be absolutely happy to contribute a PR. While I might take a try at setting such a thing up, it's likely to be a bit before I will get a chance to do so.

[romeara]

@ozscheyge I... think I got it to work? I filed #156 , so that's at least somewhere to start from

[ozscheyge]

Hey @romeara ,

I think, we are a bit stuck here, see #165 (comment)
While your proposed fix may avoid errors reported by restdocs-api-spec/Spring restdocs, it still would not lead to the desired documentation (in the target formats) of links using LinkDescriptors.

As a work-around, I'd suggest to document non-HAL links using FieldDescriptors.

How would you want to proceed here?

[ozscheyge]

Closing this and related PRs due to inactivity and lack of ideas/wishes how to solve this problem.

#156
#165