15

I am using Spring REST Docs to document a REST API. I'm trying to document the following API operations:

GET /subsystems
GET /subsystems/some_name

For example, a call to GET /subsystems/samba returns the following JSON object:

{ 
  "id": "samba", 
  "description": "..." 
}

You could use the following snippet which uses Spring REST Docs to document this API operation:

this.mockMvc.perform(
    get("/subsystems/samba").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("id").description("Subsystem name"),
            fieldWithPath("description").description("Subsystem description")));

My problem is with the first operation: the call to GET /subsystems returns a JSON array:

[ 
  { 
    "id" : "samba", 
    "description" : "..." 
  }, 
  { "id" : "ownCloud", 
    "description" : "..." 
  },
  { "id" : "ldap", 
    "description" : "..." 
  } 
]

I could not find any example showing how to document this kind of result in the Spring REST Docs documentation. How should I do it?

Andy Wilkinson
  • 108,729
  • 24
  • 257
  • 242
aaguilera
  • 1,080
  • 10
  • 27
  • i have the same problem have you resolve? – mautrok Sep 24 '15 at 14:17
  • 1
    No, sorry. Finally I decided not to use Spring REST Docs. It does not fit my needs at the moment. I think Spring REST Docs assumes a highest maturity level in the REST API (http://martinfowler.com/articles/richardsonMaturityModel.html) that my API does not fulfill (these restrictions assume you always must return a JSON object, never an array as a top-level element). Perhaps future versions of Spring REST Docs will relax these constraints for projects with simpler needs? – aaguilera Sep 26 '15 at 12:47
  • 1
    Spring REST Docs doesn't make any assumptions about the maturity level of your REST API. It provides support for level 3 APIs (allowing you to document your API's links), but can be used to document less mature APIs. In fact, the only constraint in 1.0 is that your API can be tested with Spring MVC Test. – Andy Wilkinson Dec 03 '15 at 17:36
  • Thanks @AndyWilkinson! I'll give Spring REST Docs a second chance. :-) – aaguilera Dec 11 '15 at 23:00

2 Answers2

25

this is totally possible with Spring Rest Doc 1.0

this.mockMvc.perform(
    get("/subsystems").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("[].id").description("Subsystem name"),
            fieldWithPath("[].description").description("Subsystem description")));

To document the array itself, use

this.mockMvc.perform(
    get("/subsystems").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("[]").description("An array of subsystems"),
            fieldWithPath("[].id").ignore(),
            fieldWithPath("[].description").ignore()));

I have ignored the other two fields if you just want to document the array itself. You can combine both solutions as well.

Enjoy.

Edit: I learned from Andy Wilkinson that if you document the top level array, all fields are marked as documented. So if you want to document just the array, you can safely skip the ignores.

Michael Simons
  • 4,640
  • 1
  • 27
  • 38
2

subsectionWithPath method of PayloadDocumentation works with [] as well, without necessary to ignore the rest of fields:

result.andDo(docHandler.document(
    responseFields(subsectionWithPath("[]").description("A list of objects")
)));
Cepr0
  • 28,144
  • 8
  • 75
  • 101