Implement Spring REST Docs support or implement similar functionality natively

[ptrthomas]

I only recently came to know of Spring REST Docs: https://projects.spring.io/spring-restdocs/ and it is interesting.

Spring REST Docs has built-in support for REST-Assured. IMO it is a no-brainer for Spring REST Docs to support Karate. I was impetuous enough to ask the creator of Spring REST Docs @wilkinsona to consider this (via twitter), but I'm not sure I made my point well enough.

Since my priority right now is to build a community, spread the word, and ensure any remaining rough-edges are smoothened out, implementing Spring REST Docs support is not something I have bandwidth for right now. Hence the 'help wanted' tag on this ticket.

This may be a good academic exercise for validating the design of karate-core, for example if you look at the Spring REST Docs core, it has abstractions for all the HTTP things you expect, such as operations and headers.

I'm also open to the possibility of Karate implementing a clean-room documentation approach similar to Spring REST Docs. The BIG advantage would be to make this accessible to non-Java programmers. It may be simpler because we don't have to work with the abstractions of Spring REST Docs.

[wilkinsona]

Integrating a testing library with REST Docs requires three things:

1. Access to the request that was sent
2. Access to the response that was received
3. A way to document the request and response (request and response structure, HTTP headers, hypermedia links, etc)

1 and 2 are (largely) an implementation detail that a user barely sees. The third part is where things could get interesting in the context of Karate as it's a user's main interaction point with REST Docs. If it's possible to plug in an extension to Karate's DSL, then it should be possible to write a DSL extension that maps down onto REST Docs' Java API. In other words, you could make REST Docs accessible to non-Java programmers while also reusing pretty much all of the effort that's already gone into it.

[ptrthomas]

@wilkinsona awesome, thanks. I'll do my best to dig into this on the side. IMO the DSL extension is the easiest to solve either with a new keyword or via the JS extension mechanism.

So just one question on the "access to the request" part. What would be the starting point if one were to begin this implementation. Karate uses Jersey, so I'm guessing it would just be a filter that reads the request object & context and calls the REST Docs API, populating various REST Docs domain objects.

Karate currently has one filter in action for header manipulation: (RequestFilter) and adding a Jersey ClientResponseFilter should be quite straightforward.

[wilkinsona]

So I'm guessing it would just be a filter that read the request object & context and calls the REST Docs API, populating various REST Docs domain objects.

Yes, that's right. Something needs to be plugged in that converts the "native" request into a REST Docs OperationRequest (like this one for REST Assured) and the "native" response into a REST Docs OperationResponse (like this one for REST Assured).

[ptrthomas]

@wilkinsona nice. That actually looks eminently do-able and possibly relatively quickly. BTW I just checked in a spring-boot sample that serves as a set of demos for Karate features. And it should be a good starting point for me to start experimenting. Thanks for the tips ! Will keep you posted via Twitter.

[ptrthomas]

@wilkinsona an update, thanks to @rishabhbitsg (#109) - we have very prelim support for spring-restdocs in the develop branch: https://github.com/intuit/karate/tree/e7e5e948ba6440b2c963c217a31d4b9a8a46f50f/karate-restdocs

This is not prod ready and the plan is to release karate v0.5.0 in a day or two while we figure out the best way for users to configure karate for spring-restdocs

If you get time to take a look and suggest improvements, that would be great.

BTW - Karate has a mock-servlet approach that plays well with Spring Boot / MVC - just FYI: https://github.com/intuit/karate/tree/e7e5e948ba6440b2c963c217a31d4b9a8a46f50f/karate-mock-servlet

One of the thoughts I have is for users to use the userDefined property bag (refer link above) to tell the document-er which requests to emit documentation for. It could be as elegant as an AOP-style regex.

The other option I haven't thought through fully is to use Cucumber tags - which are a native part of a Karate script. But I don't think they can be sprinkled in once a Scenario begins.

Or yes we can invent a keyword or directive like configure restdocs = true which will kick-in for the next HTTP request and disable itself.

[ptrthomas]

adding an article link for reference: http://www.sylvainlemoine.com/2017/07/29/spring-rest-docs-tutorial/

[ghost]

Hi @ptrthomas! You've probably seen it, but this project might be of interest: https://github.com/RESTDocsEXT/restdocsext-jersey.

[ptrthomas]

@stiancognite thanks ! I'll take a look.

[ptrthomas]

I'm closing this ticket. quite disappointed with the lack of interest from the community.

we will go it alone and implement this natively. may be a good thing since we can reduce any dependency bloat on spring.