Support using REST Assured to generate documentation snippets

[johanhaleby]

Hi,

I find spring-restdocs very interesting and it's definitely something that I can see myself using when writing REST API documentation if I'm using Spring as backend. I'm developing a library called REST Assured that is similar to Spring MockMvc in the sense that you test your REST/HTTP API but REST Assured is for "end-to-end" testing and is thus issuing real HTTP requests (there's also a module for spring mockmvc though). I would really like to have a module for REST Assured that allows you to document the API in a similar fashion as spring-restdocs. I haven't look into the code in great detail but it seems to me that spring-restdocs is highly coupled to spring-test. This is understandable but I wonder if it would make sense to extract a "spring-restdocs-core" that is not coupled to spring-test? This way other libraries such as REST Assured could benefit from spring-restdocs as well. It also means that the scope of spring-restdocs is extended to include other types of tests such as end-to-end tests and thus the REST API documentation could be more "complete" (for example if you have both REST Assured tests and Spring MockMvc test for the same API).

What are your thoughts on this?

Regards,
/Johan

[wilkinsona]

Hi, @johanhaleby. I'm certainly not against making Spring Rest Docs work with REST Assured, and it's something that others are interested in too (see #80). I'm only somewhat familiar with REST Assured so I probably need to spend some time familiarising myself with it and getting a feel for where Spring REST Docs needs to be decoupled from MockMvc.

[johanhaleby]

My idea (although I'm not at all sure if it's feasible) is to integrate spring-restdocs with REST Assured using a filter. A filter in REST Assured is similar to a Servlet filter in the sense that you can hook into the request and response and view/change its details. Since you have access to the request and response details I figure you ought to be able to delegate to spring-restdocs from within the filter. I imagine the REST Assured API looking something like this (off the top of my head):

given().
       param("x", "y").
       filter(document("error-example",
                    responseFields(
                        fieldWithPath("error").description("The HTTP error that occurred, e.g. `Bad Request`"),
                        fieldWithPath("message").description("A description of the cause of the error"),
                        fieldWithPath("path").description("The path to which the request was made"),
                        fieldWithPath("status").description("The HTTP status code, e.g. `400`"),
                        fieldWithPath("timestamp").description("The time, in milliseconds, at which the error occurred")))).
when().
        get("/resource").
then().
        statusCode(200);

where document is statically imported from a rest-assured-spring-restdocs module that uses spring-restdocs under the covers. I'm sure that there's a lot to workout for this to work flawlessly. For example when it comes to the path syntax. REST Assured uses GPath (but it's unfortunaltey called JsonPath in REST Assured) whereas spring-test (MockMvc) uses the defacto json-path syntax developed by Stefan Goessner (and ported to Java by a colleague of mine). I'm planning to support the Goessner syntax as well in a future version of REST Assured but I like it to be pluggable. But anyway this is just an example of where it would be great if "spring-restdocs-core" didn't depend directly on JsonPath but rather provided an SPI to extract values from the path. The "standard" spring-restdocs component could then depend on json-path and spring-test while rest-assured-spring-restdocs could depend on Groovy (for GPath) and rest-assured (instead of spring-test).

I would be happy to participate and try things out if you're interested in taking this route but I'm sure that it'll be quite a lot of work just as @sg-ad suggested in issue #80. But I think it would be a great addition both for REST Assured and spring rest docs.

[sg-ad]

Hi @johanhaleby !

It's interesting you should mention that, because I had precisely the same need a few months ago. I was in love with the idea of Spring Restdocs, but needed it to work with REST Assured. I also added some tidbits of functionality that weren't supported at the time (Spring Restdocs has evolved since I originally forked it and I needed support for path parameters).

The challenge that I had was decoupling the code from Spring's MvcResult. Unfortunately, REST Assured doesn't yet offer as rich of a result object, and the things a REST Assured filter has access to are very limited. To get a "rich" access, I had to go down to the level of the HTTP client. Fortunately, REST Assured allows you to do this in a fairly straightforward fashion by modifying the config to introduce your own factory:

RestAssured.config = RestAssured.config()
    ...
    .httpClient(HttpClientConfig.httpClientConfig().httpClientFactory(new RestAssuredDocumentingHttpClientFactory()))
    .decoderConfig(decoderConfig().noContentDecoders().defaultContentCharset("UTF-8"))
    .encoderConfig(encoderConfig().defaultContentCharset("UTF-8"));

All the new RestAssuredDocumentingHttpClientFactory factory does is add request and response interceptors which give me access to most of the useful information, with one exception: I can't get my hands on the OAuth information because it is added by an internal interceptor added by REST Assured in such a way that it will always run after any interceptor I might add. It makes sense, because you wouldn't want to allow tampering of the request after it gets signed, but in my case it's quite unfortunate. Ideally one could still intercept it but the request would be wrapped in a way to make it immutable. Anyway, that's another discussion... :) Another limitation is that while it is thread-safe, it won't support asynchronous calls but I find that is rarely a need for tests.

To keep the usage similar to that of Spring Restdocs, I introduced a simple REST Assured filter and kept the static approach for a document method. The result looks like this:

given()
    .filter(document("subscriptions-delete-example")
        .withRequestPathParams(pathParam("subscriptionId").description("ID of subscription to cancel.")))
    .auth().oauth(APPLICATION_OAUTH_KEY, APPLICATION_OAUTH_SECRET, "", "")
    .when()
        .pathParam("subscriptionId", newCompanyEntitlement.getUuid())
        .delete("/api/v1/subscriptions/{subscriptionId}")
    .then()
        .statusCode(Status.NO_CONTENT.getStatusCode());

The next difficulty was that the MvcResult is passed around in a lot of internal pieces to Spring Restdocs; the SnippetWriters after all need access to it. This caused me to have to create a whole parallel structure where my new snippet writers would take Apache's HttpRequest, HttpResponse and HttpContext instead of MvcResult. This quickly devolved in a lot of code replication where sometimes all that changed were the import statements. That's basically what I described in #80 and was seeking suggestions. What I would like to do is to somehow refactor it so that it could live next to Spring Restdocs and benefit from enhancements, or at least make those enhancements easily portable. At the moment I haven't kept up-to-date with the latest releases of Spring Restdocs and it would be a real shame if this caused my implementation to go stale.

Anyway, I think the right first step is for me to share my work as @wilkinsona suggested so that we can see where it might live - or, better yet, how it could best be refactored to "come home" to Spring Restdocs. July was a bad month and I was also on vacation for a bit, but I'll endeavour to make something publicly available over the next few days to get your comments.

Cheers!

[johanhaleby]

Thanks for some great input @sg-ad! I think it would be great if you could share your project and if you want to continue collaborating. May I ask what data you couldn't get a hold of from the REST Assured filter? I'll be happy to make changes to the FilterableRequest-/ResponseSpecification (as long as it doesn't break backward compatibility) if that would make things easier. I hope that we manage to solve this using only a filter since having to register a custom HttpClientFactory seem quite complex to me.

[sg-ad]

Hi @johanhaleby! The difficulty I had with RestAssured was related to logging example requests. I was hoping to show examples that were as close to reality as possible. Because a Filter only sees request and response specifications, it can't provide information as to other headers that are added by the HttpClient (ex: keep-alive, host). It also couldn't show OAuth related headers. The result was that I could only capture "partial" examples, so to speak. Granted, you could argue that headers that aren't in the specification might not contribute much to the documentation, but I found that it made it a bit nicer. However, the one thing I could never get my hands on - even with my alternative approach - were the OAuth headers.

I don't know how complicated it would be for RestAssured to provide post-response access to the entire request and response, akin to what an MvcResult exposes. That would allow one to log the whole request, including the OAuth headers, without exposing a tampering opportunity since it would only be available after the request completed. Do you know if that would be easily feasible?

[johanhaleby]

@sg-ad I would very much like to log all headers but I haven't found a way to do so. To my knowledge the only way to do it is to enable wire-level logging in Apache HTTP Client (AHC). Do you know if AHC has support for something similar to filters? Perhaps it would be possible to get a hold of the headers then? Was this why you provided your own HttpClient instance?

[sg-ad]

@johanhaleby What I found is that since the HTTP client currently used by Rest Assured (RA) is an instance of Apache HTTP Client (AHC), I could use the functionality it exposes. It allows you to register some HttpRequestInterceptor and HttpResponseInterceptor, similar to an RA Filter except that you can fully modify the request and response. What I envision could be done is to have RA register a final interceptor that would take a snapshot of the request in its final form and store it in a container on the side. Once the response comes back, another interceptor could take a snapshot of the response and store it in the same container. This info container could be provided to user code a bit like MvcResult is. The interceptor would have to be the last one to process the request, and the first one to process the response.

The interceptors are said to be executed in the order in which they are registered. Since RA creates the AHC and doesn't easily expose it to manipulation, it could safely add that interceptor in as the last step. However, one critical thing is that it should be added after the OAuthSigner interceptor is added. Currently it's the last one added (for a very good reason since you don't want the request to be modified after the signature has been calculated). We would have to find a correct place in RA to add such an interceptor. I'd be happy to help in this if you think it's a good approach.

[johanhaleby]

I like your idea.. Perhaps it could work if we create new RA Filter from which we get the AHC instance and register a HttpRequestInterceptor that extracts the header details and put them in the filter context? For example:

given().
        filter((requestSpec, responseSpec, ctx) -> {
            AbstractHttpClient ahc = (AbstractHttpClient) requestSpec.getHttpClient();
            ahc.addRequestInterceptor((request, context) -> {
                Header[] allHeaders = request.getAllHeaders();
                ctx.setValue("ahc-headers", allHeaders);
            });
            return ctx.next(requestSpec, responseSpec);   
        }). ..

Now when the request comes back the headers should be present in RA's filter context. Would this help?

[wilkinsona]

The Operation abstraction appears to be holding up. I have the very beginnings of REST Assured support working in this branch: https://github.com/spring-projects/spring-restdocs/tree/rest-assured. It successfully produces the curl request snippet for the simplest possible request.

[johanhaleby]

@wilkinsona Cool! Glad to see that there the progress so far.