spring-projects
Produce URI Snippet
It would be useful to be able to document a resources URI as part of documenting a given resource, this could use the custom scheme, server and port as configured in mock mvc.
It would be great if it could also include placeholders so output could something like
http://api.example.com/resources
for a collection, or
http://api.example.com/resources/{id}
For an individual resource
Bonus points if it could also produce a path variable table that could describe path variables like {id} above.
This would be obviously useful to document consumers, but also for producers as they wouldn't have to coordinate between the request snippets produced by restdocs and 'hardcoded' URIs in the asciidoc templates.
Bonus points if it could also produce a path variable table that could describe path variables like {id} above.
This is already possible using the path parameters snippet.
It would be useful to be able to document a resources URI as part of documenting a given resource, this could use the custom scheme, server and port as configured in mock mvc.
Generally speaking, I'm not keen on encouraging people to prominently document URIs. It leads to brittle documentation and can undo all of the hard work and benefits of adopting hypermedia. Unless there's an overwhelming number of people who would like this to be supported out of the box, I'd prefer to leave it as something that you add yourself. It's only a handful of lines:
public class UriSnippet extends TemplatedSnippet {
public UriSnippet() {
super("uri", null);
}
@Override
protected Map<String, Object> createModel(Operation operation) {
Map<String, Object> model = new HashMap<>();
model.put("uri", operation.getRequest().getUri());
return model;
}
}
The accompanying template, named uri.adoc in src/test/resources/org/springframework/restdocs/templates would look something like this:
{{uri}}
The new snippet can then be used like this:
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("uri-snippet-example", new UriSnippet()));
Alternatively, you could configure it as one of the default snippets so that it's always generated.
Fantastic, thanks for the really useful reply. I guess I thought that seeing as the URI is in all the curl snippets anyway it wouldn't be that much of a stretch to have it on it's own. Well now you've given me the technique to do it, that's great, thanks so much. Love this project BTW, am mandating it's adoption for all internal and external APIs in my organization.
Given that no one else has requested this, it's simple to roll your own, and explicitly documenting URIs isn't something I'm keen to encourage, I'm going to close this one.
I'm willing to look at creating a PR for this - as far as I understand, the main desired element not currently supported by provided snippets is standardized documentation of the URI (template-style).
I'll look to include that URI, and in addition the verb and accept/content-type headers in the snippet as an initial proposal (from experience thus far, those three elements are what are most important to uniquely identifies a resource on an application)
