java - document hierarchical JSON payload with Spring REST Docs -

i started use spring rest docs document simple rest api. have payload has hierarchical structure, example (company employees).

{     "companyname": "foobar",     "employee":      [         {             "name": "lorem",             "age": "42"         },          {             "name": "ipsum",             "age": "24"         }     ] } 

i separate documentation of company object (name , array of employees) , employee object (employee name , age).

using org.springframework.restdocs.payload.payloaddocumentation.responsefields explained here forces me document fields in case want document employee fields - how can achieve this?

i have no problem document company without employee details because if field document descendants treated been documented also. can not document employee structure on own , have no dedicated payload structure without company root object.

inspired question, i've implemented enhancement makes original answer (see below) obsolete.

if use 1.0.0.build-snapshot (available https://repo.spring.io/libs-snapshot), can mark field ignored. ignored fields count has having been documented without appearing in documentation.

given want separate documentation, having 2 document calls makes sense. in first can document company name , array of employees. in second document employees array , mark company name ignored.

your test this:

mockmvc.perform(get("/company/5").accept(mediatype.application_json))         .andexpect(status().isok())         .anddo(document("company",                 responsefields(                         fieldwithpath("companyname").description(                                 "the name of company"),                         fieldwithpath("employee").description(                                 "an array of company's employees"))))         .anddo(document("employee",                 responsefields(                         fieldwithpath("companyname").ignored(),                         fieldwithpath("employee[].name").description(                                 "the name of employee"),                         fieldwithpath("employee[].age").description(                                 "the age of employee")))); 

you'll end 2 directories of snippets, 1 named company , 1 named employee. can use response-fields.adoc snippet each.

original answer

there's no explicit support ignoring field when you're documenting request or response, think can achieve want using preprocessor remove fields don't want document.

given want separate documentation, having 2 document calls makes sense. in first can document company name , array of employees. in second need preprocess request remove company , document employees array.

your test this:

mockmvc.perform(get("/company/5").accept(mediatype.application_json))         .andexpect(status().isok())         .anddo(document("company",                 responsefields(                         fieldwithpath("companyname").description(                                 "the name of company"),                         fieldwithpath("employee").description(                                 "an array of company's employees"))))         .anddo(document("employee",                 preprocessresponse(removecompany()),                 responsefields(                         fieldwithpath("employee[].name").description(                                 "the name of employee"),                         fieldwithpath("employee[].age").description(                                 "the age of employee")))); 

note use of preprocessresponse in second document call. removecompany returns preprocessor uses custom contentmodifier remove company name response:

private operationpreprocessor removecompany() {     return new contentmodifyingoperationpreprocessor(new contentmodifier() {          @override         public byte[] modifycontent(byte[] originalcontent, mediatype contenttype) {             objectmapper objectmapper = new objectmapper();             try {                 map<?, ?> map = objectmapper.readvalue(originalcontent, map.class);                 map.remove("companyname");                 return objectmapper.writevalueasbytes(map);             }             catch (ioexception ex) {                 return originalcontent;             }         }      }); } 

you'll end 2 directories of snippets, 1 named company , 1 named employee. can use response-fields.adoc snippet each.

while above work, it's harder needs be. i've opened an issue preprocessing modify response's content no longer necessary.