search

spring-projects / spring-restdocs

Test-driven documentation for RESTful services
https://spring.io/projects/spring-restdocs
Apache License 2.0
1.16k stars 736 forks source link

Support hook to allow easier programmatic link traversal #72

Closed andreasevers closed 9 years ago

andreasevers commented 9 years ago

As mentioned in my blog a couple weeks ago, I was talking with Oliver Gierke at Spring I/O about possible documentation solutions.

At my client I am integrating most of the stuff you can find in foxycart's HAL browser but in a dynamic way. Exposing a graph of resources can be done using Spring Restdocs' link documents generated in asciidoc. By parsing the results of these asciidocs and merging the results, a resulting json is aggregated and used to generate a graph of resources and their links using d3js. This graph is integrated in the HAL browser, and each resource links to its documentation. That documentation per resource can of course also be reached from the regular HAL browser documentation links using curies.

What would the best solution be for this approach? Parsing the generated links.adoc isn't as easy as it could be. Maybe a hook could be supported in the generation model to allow us to expose links.json on top of links.adoc.

wilkinsona commented 9 years ago

Have you looked at using a LinkExtractor on the response from the MockMvc call? It gives you a Map of links keyed by href:

MockHttpServletResponse response = mockMvc.perform(get("/")).andReturn()
        .getResponse();
LinkExtractor linkExtractor = LinkExtractors.extractorForContentType(response
        .getContentType());
Map<String, List<Link>> links = linkExtractor.extractLinks(response);

You would then be free to write out the links in whatever format you need.

wilkinsona commented 9 years ago

@andreasevers Sorry, I forgot to mention you in my comment above

andreasevers commented 9 years ago

Oh no problem, I'm subscribed anyway :)

I'll for sure try this out. It seems like a way easier approach than what I was using as of now.

When I'm done I'll try to showcase the eventual solution which should be pretty nice in the HAL browser.

wilkinsona commented 9 years ago

Great, thanks. I'll look forward to the showcase.

I'm going to close this for now. If the LinkxExtractor-based approach doesn't work out, we can re-open it and figure out an alternative.