Spring Auto REST Docs + Spring Data REST? HATEOAS?

Question

I really like the idea of using Javadoc comments for auto-generating REST Docs!

Huge parts of our REST API are automatically generated by Spring Data REST (by adding @RepositoryRestResource to Repositories). It would be great if REST Docs could also be generated for these - that would be a very high degree of automatition.

But unfortunately most "auto-"snippets are "empty" (e.g. auto-response-fields.adoc only contains a list of links[]-Attributes). I guess the reason could be that the REST Controllers are probably created dynamically by Spring Data REST. Currently I do not see how to re-use the Javadoc comments for them.

Is there any way to auto-generate REST Docs for such REST APIs that are provided by Spring Data REST? It would even be helpful to manually tell Spring Auto REST Docs which classes are used in requests and responses instead of letting it discover it statically - is that possible?

And we also add HATEOAS "_links" to most response Resources (by providing ResourceProcessors as Beans). These links contain "title"s which are used by Spring REST Docs - if we list all of them with HypermediaDocumentation.linkWithRel(...). This is a bit redundant, and it would be nice if all the _links with "title"s could be processed automatically. (But this can be done by listing all of them in some extra code, so it is not as bad as with Spring Data REST.)

If necessary, I could also create an example project for what I am talking about.

Answer 1

Answer to the question whether one can manually tell Spring Auto REST Docs which classes to use for the documentation:

Spring Auto REST Docs allows to specify the request and response classes to use for the documentation. This can be done with requestBodyAsType and responseBodyAsType. In a test it looks like this:

  .andDo(document("folderName",
    requestFields().requestBodyAsType(Command.class),                    
    responseFields().responseBodyAsType(CommandResult.class)));

This is from a test in the example project.