ascii doc response-fields.adoc missing when using only ResourceDocumentation.resource

[alexisparis]

Hi,

Initially, I was using classes from spring-restdocs to document an api and the generated snippets used to include every type of asciidoc needed, including the files response-fields.adoc. Then, I switched to ResourceDocumentation to be able to specify the schema. Here is an example :

    @Test
    public void getDriver() throws Exception {
        WebTestClient.BodySpec<Driver, ?> driverBodySpec = webClient.get().
            uri("/drivers/{id}", 1).
            accept(MediaType.APPLICATION_JSON).
            header("HEADER", "value").
            exchange().
            expectStatus().isOk().
            expectBody(Driver.class).
            consumeWith(
                    WebTestClientRestDocumentationWrapper.document(DOCUMENT_IDENTIFIER, "get a driver by its id",
                        ResourceDocumentation.resource(
                                ResourceSnippetParameters.
                                        builder().
                                        requestHeaders(
                                                HeaderDocumentation.
                                                        headerWithName("HEADER").
                                                        optional().
                                                        description("optional header when retrieving a driver")
                                        ).
                                        pathParameters(
                                                ResourceDocumentation.
                                                        parameterWithName("id").
                                                        description("the id of a driver").
                                                        type(SimpleType.INTEGER)
                                        ).
                                        responseFields(this.driverFieldDescriptors).
                                        responseSchema(Schema.schema("Driver")).
                                        build()
                        )
                        // todo : find a way to avoid duplication : if not there, no response-fields.adoc generated
                        , PayloadDocumentation.responseFields(this.driverFieldDescriptors)
                    ));
        driverBodySpec.consumeWith(body -> Assertions.assertEquals(driverJohnDOE, body.getResponseBody()));
    }

I realized that I have to duplicate the responseFields in order for the response-fields.adoc to be generated.

Is there another way to do the same without duplicating this part?

[ozscheyge]

Hey @alexisparis ,

yep, in general, we provide various document functions wrappers for mockmvc, restassured and webtestclient as import-swap-replacements for the respective document methods. And then we provide some additional document signatures to offer more control like in your use-case, which is totally valid.

Normally, we should extract all Restdocs snippets from our resource snippet and pass them on to the wrapped document methods:

1. Copying the snippets from the resource snippet: https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-webtestclient/src/main/kotlin/com/epages/restdocs/apispec/WebTestClientRestDocumentationWrapper.kt#L25 https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/RestDocumentationWrapper.kt#L25
2. Passing them on, e.g. https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-webtestclient/src/main/kotlin/com/epages/restdocs/apispec/WebTestClientRestDocumentationWrapper.kt#L44

I see no apparent error, but there seems to be one. As a starting point, https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-webtestclient/src/test/kotlin/com/epages/restdocs/apispec/WebTestClientRestDocumentationWrapperIntegrationTest.kt could be extended to not just assert the existence of the resource.json snippet, but also other Spring Restdocs snippets, which should still be generated. That could lead us closer to the root cause. One experiment could also be passing the responseFields snippet to the document method and not to ResourceSnippetParameters, then see what happens.

Would you mind investigating further by extending the tests and maybe providing a PR?

[alexisparis]

@ozscheyge ok, I am gonna try to extend the test based on your information