Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Andy Wilkinson
    @wilkinsona
    Things are a bit painful at the moment with the latest and greatest in the Asciidoctor world as their latest majors and minors include some breaking changes
    I haven't had a chance to experiment with the 2.x line yet
    Andy Wilkinson
    @wilkinsona
    @kschlesselmann I've just done a bit of experimentation and couldn't reproduce the failure. spring-restdocs-asciidoctor doesn't work but that's a different and known (spring-projects/spring-restdocs#581) problem. Can you share a sample build that fails with Collection is empty?
    Knut Schleßelmann
    @kschlesselmann
    I'll try to provide one (currently rather tight schedule here :-S)
    Carlos Adolfo Ortiz Q
    @cortizqgithub

    @cortizqgithub are you using maven or gradle?

    Sorry for replying late. @jlstrater I want to be confident in using Spring Rest Docs in particular and Asciidoc in general, I mean, I would like to understand the right configurations needed in a sole maven project for creating Docs. Sometimes the Asciidoctor documentation is confusing.

    Carlos Adolfo Ortiz Q
    @cortizqgithub
    Besides I would like to use Asciidoctor V2 train
    Srinivas
    @bodasrinivas
    Hi Every one . I m checking out can some help me with a knowledge or link how to build end to end application using rest and spring . I had done my homework couldn’t able to understand the exact flow of application.
    Matija Folnovic
    @mfolnovic

    hello! i've noticed that, for a request with a required request parameter, these two behave differently:

    • document("{class-name}/{method-name}") - doesn't fail
    • document("{class-name}/{method-name}", requestParameters()) - fails

    and I was just wondering if someone could explain what's a reason behind this decision? tnx!

    Andy Wilkinson
    @wilkinsona
    @mfolnovic By adding requestParameters(), you're telling REST Docs that you care about the request parameters and you want them to be documented. In other words, you need to opt in to the various pieces that you want to document and that you want REST Docs to check for you.
    Matija Folnovic
    @mfolnovic
    I get that from documentation perspective, but not from testing if I have documented everything perspective :)
    Andy Wilkinson
    @wilkinsona
    IMO, things would be too cumbersome if you had to opt out
    Matija Folnovic
    @mfolnovic
    It's clear to me when you would want to opt out :see_no_evil:
    But I'm new to this, still learning, so... :blush:
    But I'd genuinely like to understand why this would be a bad idea :see_no_evil:
    Matija Folnovic
    @mfolnovic

    It's clear to me when you would want to opt out :see_no_evil:

    sorry, wanted to say "It's not clear to me..."

    Andy Wilkinson
    @wilkinsona
    It really depends on the type of documentation that you're writing. You might be walking through something and at a point where only, say, the response body, is of interest. Having to opt out of everything that REST Docs can document just to be able to do that would be quite cumbersome
    The other aspect of it is extensibility. Right now, third-parties can add new snippets with their own requirements that can be used by adding a dependency and passing the snippet to document. With an opt-out approach, I'm not sure how that would work. We could use some sort of extension mechanism to plug snippets in without the user having to do anything, but they then get all their tests blowing up and would have to opt out everywhere they didn't want the new snippet type to apply.
    Matija Folnovic
    @mfolnovic
    Understood, tnx! :)
    Knut Schleßelmann
    @kschlesselmann
    Can I somehow ignore missing template values? I'd be nice to document the value range and default values for request fields … now my tests fail with org.springframework.restdocs.mustache.MustacheException$Context: No method or field with name 'defaultValue' on line 8 because not every snippet has those values
    Knut Schleßelmann
    @kschlesselmann
    It seems |{{#defaultValue}}{{.}}{{/defaultValue}} is a workaround :-)
    Andy Wilkinson
    @wilkinsona
    @kschlesselmann That's the best (least bad?) way of doing it with Mustache that I know of. In case you haven't already seen it, there's some discussion about that approach in spring-projects/spring-restdocs#291.
    Carlos Adolfo Ortiz Q
    @cortizqgithub
    @wilkinsona Can you provide me with a tutorial, gist, or anything else where I can learn how to document a Spring WebFlux RestController? Thank you.
    Andy Wilkinson
    @wilkinsona
    @cortizqgithub Assuming that you want to use WebTestClient, there's a sample in the REST Docs repo that should help: https://github.com/spring-projects/spring-restdocs/tree/master/samples/web-test-client
    The sample uses a RouterFunction rather than a @Controller, but the principle's the same on the testing and documentation side.
    Carlos Adolfo Ortiz Q
    @cortizqgithub

    @wilkinsona Thanks. But here I have another question.
    I have this Maven Dependency

    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.7.1</version>

    I wonder if you had upgraded project samples to V2 of it.
    I now see that V1.6 is the latest for this plugin.
    Besides. I found a most modern way to do so.

    @Test
    public void shouldReturnChuckNorrisData() {
    this.webTestClient.get()
    .uri("/api/v1/chuck/norris/random/string")
    .exchange()
    .expectStatus()
    .isOk()
    .expectBody()
    .consumeWith(document("random-string"));
    }

    Is your example using an old way to do matters

    Andy Wilkinson
    @wilkinsona
    That test looks very similar to the one in the example. What in the sample did you consider to be the old way?
    Carlos Adolfo Ortiz Q
    @cortizqgithub

    Never mind, it is the same, what I see different is this
    @Rule
    public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

    FOr configuring.
    I think this is old
    New way is with the annotations.

    Andy Wilkinson
    @wilkinsona
    It's not really new vs old there. The annotation-based approach is only available if you're using Spring Boot which that sample is not.
    Carlos Adolfo Ortiz Q
    @cortizqgithub
    Got it. Thanks!
    luvarqpp
    @luvarqpp
    Hello here. I have started some discussion (question) on github issue. I would like to continue here as @wilkinsona suggested. Issue spring-projects/spring-restdocs#666 . My question is about right way of assembling documentation parts for some request/response.
    Andy Wilkinson
    @wilkinsona
    Hi, @luvarqpp
    luvarqpp
    @luvarqpp
    Is there some "real world" project which is documenting many things in modular manner? i.e. when response is a projection, which passes as response two entities (their fields), how to combine and reuse modules (snippets descriptions) from each single entity test.
    for esample, I have User and Invoice. Both have their repository and both are capable of CRUD. Both documented
    now I introduce Invoice projection, which have materialized its author (User) in its response. How to reuse documentation of User fields inside test and documentation of augmented Invoice?
    luvarqpp
    @luvarqpp
    I have read it some time ago and it seems that I have missed a bit... A few sections to be precise... Thanks
    Sarvesh Dubey
    @Sarvesh-D
    Hi, is it possible to document generic response like BaseResponse<T>. We have a generic base response class which is extended by various response classes.
    Andy Wilkinson
    @wilkinsona
    @Sarvesh-D REST Docs doesn't care about the Java types of the responses as it works at the level of (mocked) HTTP requests and responses.