spring-restdocsspring-auto-restdocs

Spring-restdocs field description from annotations

Is it possible to use annotations (at field-level) to provide description for fields?

I know I can use description method for that

.andDo(document("index", responseFields( 
            fieldWithPath("contact").description("The user's contact details"),

but I would prefer to put that description together with field definition, in my response object.

class IndexResponse {
 //The user's contact details
 String contract;
}

I know that I could have generated constraint descriptions (http://docs.spring.io/spring-restdocs/docs/current/reference/html5/#_using_constraint_descriptions_in_generated_snippets) but it generated description only for validation annotations.

I am looking for something like https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodelproperty from Swagger.

Solution

  • We built an extension to Spring REST Docs that allows using Javadoc for field descriptions:

    class IndexResponse {
  /**
   * The user's contact details
   */
  String contract;
}

    But currently this only works if Jackson and MockMvc tests are used.

    Project: https://github.com/ScaCap/spring-auto-restdocs

    An introduction article: https://dzone.com/articles/introducing-spring-auto-rest-docs