Create Kotlin DSL for Spring RestDocs

[checketts]

I've been working on a Kotlin DSL for restDocs and have converted a number of samples to demonstrate it.

I would love to contribute the DSL into the spring-restdocs project. Would you be interested in that DSL? (I also wanted to contribute the base MockMVC DSL to spring test, but that is a different project)

Example DSL:

    @Test
    fun indexExample() {
        this.mockMvc.performGet("/") {
            expect { status { isOk } }
            document(documentationHandler) {
                "notes" link { description("The <<resources-notes,Notes resource>>") }
                "tags" link { description("The <<resources-tags,Tags resource>>") }
                response {
                    "Content-Type" header { description("The Content-Type of the payload, e.g. `application/hal+json`") }
                    "_links" subsection { description("<<resources-index-links,Links>> to other resources") }
                }
            }
        }
    }

[cezary-butler]

Great idea.
Why not work on it separately and merge it to spring when it's been proven useful and stable?

Lately I've been working with spring rest-docs and kotlin, maybe I could also contribute.

[checketts]

Cool! This issue was to gauge interest and collaboration. At this point. I believe the underlying code is ready for contribution. I played with converting 3 of the samples and they all worked out well. (not to mention my own project's tests)

So I'll move forward with creating a pull request.

Ideas going forward:

• It relies on https://github.com/petrbalat/kd4smt, which is being published to an unusual maven repo. I would love to see that code (most of which I contributed) moved into SpringTest.
• I'll add the kd4smt lib as an optional dep for now while creating the PR
• Instead converting an existing sample, I'll create a new sample so as not to muddy the existing samples

[wilkinsona]

Yes, I'm definitely interested in a Kotlin DSL. Thanks for the offer of a contribution. @sdeleuze is our resident Kotlin expert so I'm hoping we can get him involved in this too. #192 may also be somewhat relevant here.

The use of kd4smt may be a bit problematic, particularly if it's not in Maven Central, but it needn't block things at this early stage.

[sdeleuze]

Sure, I will have a look asap.

[checketts]

I've opened the PR spring-projects/spring-framework#1951 to move the kd4smt DSL into Spring Test itself.

While iterating on that PR, I'll get started on the PR for this repo too

[mduesterhoeft]

This is really interesting. I also started playing with this a little. Mainly because I wanted to learn about writing a kotlin-dsl.

I find the example by @checketts very interesting - but also a little bit too much. Especially because it seems to use extension functions for String to construct e.g. a LinkDescriptor.

I think something like the sample below could be an alternative. It is closer to the proposal in #192.

.andDo(document("some") {
	request {
		field("some") { description("some") }
		field("more") { description("more")}
		header(CONTENT_TYPE) { description("some") }
	}
	response {
		field("some") { description("some") }
		field("more") { description("more")}
		link("self") { description("self link") }
	}
})

What do you think?

For details see also https://github.com/mduesterhoeft/restdocs-kotlin-dsl

[checketts]

@mduesterhoeft Do you view the extension function on String as a negative?

Keep in mind that extension functions don't leak all over the place (like monkey patching in other languages), it is actually scoped only to the document block.

That approach is pretty common in DSLs. The one negative I could think of is if you didn't know it existed looking for autocomplete in the response block works better with the field() you provided.

[mduesterhoeft]

@checketts your link to the sample code does not work (anymore). Would be interesting to look at the code.

Actually I wanted to discuss here a bit about designing the DSL - I think the string extension function approach is not really contributing to readability. But that might be a question of taste...

[wilkinsona]

Yeah, I think a lot of DSL design is a question of taste. Something that I'd like to explore is having a Kotlin DSL that looks like a more concise version of a Java API rather than being radically different. That may mean that this issue and #192 need to be worked on in tandem. That said, I'm not sufficiently experienced with Kotlin to know if that's likely to yield an idiomatic result. @sdeleuze and anyone else who's more experience with Kotlin, I'd welcome your input here please.

[checketts]

I'd like to explore is having a Kotlin DSL that looks like a more concise version of a Java API rather than being radically different.

Thanks for the direction @wilkinsona

@mduesterhoeft I've fixed the link above.

[jnizet]

I've discovered this issue after I also tried creating a Kotlin DSL for Spring REST Docs: https://github.com/Ninja-Squad/spring-rest-docs-kotlin. See the README for links to examples. I think it's a bit closer to the Java DSL.

Feedbacks welcome :-)

[sdeleuze]

Hey, after a look to the various proposals, I think I would like to take @jnizet proposal as starting point, as @wilkinsona said DSL is a matter of taste, but I think we should try to be consistent with what I have done in beans { } and router { } DSLs which indeed stay pretty close of the Java DSL.

@jnizet The direction taken by https://github.com/Ninja-Squad/spring-rest-docs-kotlin looks great, I like the andDocument principle. I am a little bit concerned by the number of top level functions like pathParametersSnippet that I would like to try to limit, is it possible to limit their scope? Maybe #192 will help, not sure.

Before that, I want to move forward on modifying and merging spring-projects/spring-framework#1951 in Spring Framework master branch, and potentially do the same for WebTestClient. I will add a comment here what that will be done.

[wilkinsona]

Thanks, both.

I am a little bit concerned by the number of top level functions like pathParametersSnippet that I would like to try to limit, is it possible to limit their scope? Maybe #192 will help, not sure.

I share this concern about REST Docs in general. In the current Java API there are lots of static methods that aren't easy to discover. I'm hoping that #192 will help. I have a rough idea of a more AssertJ-like API but haven't yet had time to really explore what that may look like.

[jnizet]

I also agree. Ideally, none of those top-level functions would exist, and that's the goal of the scopes: be able to use, for example:

.andDocument {
    pathParameters {
        add("productId", "the ID of the product to get")
    }
}

In the above example, andDocument is an extension function (for MockMvc, WebTestClient or RestAssured), pathParameters is a member function of DocumentationScope, and add is a member function of PathParametersScope.

I added these top-level functions to create reusable descriptors and reusable snippets, which can be valuable

• when the same descriptors/snippets must be used inside several tests,
• to ease the transition between the Java DSL and the Kotlin DSL, when such reusable snippets are used
• to make sure the Kotlin DSL allows doing what the Java DSL allows

But I agree that it makes a lot of top-level functions.
I'm not sure how to best scope them. My intuition would be to create two objects:

object Snippets {
    fun pathParameters(...) = ...
    fun requestParameters(...) = ...
    fun requestFields(...) = ...
    ...
}
object Descriptors {
    fun parameter(...) = ...
    fun field(...) = ...
    fun requestPart(...) = ...
    ...
}

This would remove all top-level functions while keeping the functionality. Instead of using

val reusablePathParameters = pathParametersSnippet { ... }
val reusableField = field(...)

we would use

val reusablePathParameters = Snippets.pathParameters { ... }
val reusableField = Descriptors.field(...)

which, IMHO, makes it a liitle bit more verbose, but as or even more readable.
Those objects could be the target for custom extension functions too.

What do you think?