CODEWITHSUNDEEP
javaspringdocumentationspring-restdocs
Nielsen Martins Gonçalves
Nielsen Martins Gonçalves

Reputation: 372

How to document list of objects using Spring Rest Docs

I'm using Spring Rest Docs to document my REST API. I'm using mockMVC in my integrated tests and I want to document the following JSON response:

GET /api/v1/customers/3b658b39-4264-4995-99d8-90a1672a75a7

{
    "id": "3b658b39-4264-4995-99d8-90a1672a75a7",
    "name": "Foo",
    "nickname": "Bar",
    "phones": [
        {
            "id": "6ca3a963-bacb-4770-a470-5902b4a17b77", 
            "alias": "Personal Phone 1",   
            "countryCode": "55",
            "areaCode": "34",
            "number": "99999-9999"
        },
        {
            "id": "f3a3726b-b5f8-4652-a044-7bf3d95a37de",
            "alias": "Personal Phone 2",    
            "countryCode": "55",
            "areaCode": "34",
            "number": "88888-8888"
        }
    ]
}

How can I document the list of phones above? You could use the following snippet which uses Spring REST Docs to document this API operation:

this.mockMvc.perform(
    get("/api/v1/customers/3b658b39-4264-4995-99d8-90a1672a75a7")
       .accept(APPLICATION_JSON))
       .andExpect(status().isOk())
           .andDo(document("customer").withResponseFields(
               fieldWithPath("id").description("Unique identifier"),
               fieldWithPath("name").description("Customer full name"),
               fieldWithPath("nickname").description("How the customer wants to be called")));

Upvotes: 1

Views: 4080

Answers (1)

William Okano
William Okano

Reputation: 392

According to this link https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api-request-response-payloads-fields-json

When documenting nested through array objects, you can use like this:

this.mockMvc.perform(
get("/api/v1/customers/3b658b39-4264-4995-99d8-90a1672a75a7")
   .accept(APPLICATION_JSON))
   .andExpect(status().isOk())
       .andDo(document("customer").withResponseFields(
           fieldWithPath("id").description("Unique identifier"),
           fieldWithPath("name").description("Customer full name"),
           fieldWithPath("nickname").description("How the customer wants to be called"),
           fieldWithPath("phones[].id").description("PHONE ID DESCRIPTION"),
           fieldWithPath("phones[].alias").description("PHONE ALIAS DESCRIPTION"),
           fieldWithPath("phones[].countryCode").description("PHONE COUNTRY CODE DESCRIPTION"),
           fieldWithPath("phones[].areaCode").description("PHONE AREA CODE DESCRIPTION")
           fieldWithPath("phones[].number").description("PHONE NUMBER DESCRIPTION")
        ));

Upvotes: 6

Related Questions