Как документировать массив верхнего уровня в качестве полезной нагрузки ответа с помощью Spring REST Docs

Я использую Spring REST Docs для документирования REST API. Я пытаюсь документировать следующие операции API:

GET /subsystems
GET /subsystems/some_name

например, вызов GET /subsystems/samba возвращает следующий объект JSON:

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

вы можете использовать следующий фрагмент, который использует Spring REST Docs для документирования этой операции API:

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")));

моя проблема заключается в первой операции: вызов GET /subsystems возвращает массив JSON:

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

Я не смог найти ни одного пример, показывающий, как документировать такой результат в документации Spring REST Docs. Как мне это сделать?

6
java json rest spring spring-restdocs

2 ответов

это полностью возможно с 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")));

чтобы документировать сам массив, используйте

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()));

я проигнорировал два других поля, если вы просто хотите документировать сам массив. Вы также можете комбинировать оба решения.

наслаждайтесь.

Edit: я узнал от Энди Уилкинсона, что если вы документируете массив верхнего уровня, все поля помечаются как документированные. Поэтому, если вы хотите документировать только массив, вы можете безопасно пропустить игнорирует.

15

subsectionWithPath метод PayloadDocumentation работает с [] а также, без необходимости игнорировать остальные поля:

result.andDo(docHandler.document(
    responseFields(subsectionWithPath("[]").description("A list of objects")
)));
0