Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    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.
    Eric Turley
    @ericjturley

    Probably asked a million times:
    I'm probably just missing it, but is there a way to:

    • Use @AutoConfigureRestDocs
    • Still configure for prettyPrint

    without making an intermediate documentWith() method that adds prettyPrint ?

    I'm willing to configure it in the @BeforeEach for all documentation classes, if I could get a handle to configuring the mockMvc...

    Andy Wilkinson
    @wilkinsona
    @ericjturley A RestDocsMockMvcConfigurationCustomizer bean should let you do what you want to do
    The second example here is roughly what you want to do when you customizer is called
    configurer.operationPreprocessors().withResponseDefaults(prettyPrint())
    Eric Turley
    @ericjturley
    Thanks, @wilkinsona !
    Double-thanks for the example. I was just gonna figure it out. :)
    Eric Turley
    @ericjturley
    Is there a way to combine the spring-asciidoctor-extensions-block-switch lib and an operation macro containing multiple snippets?
    Or - is it necessary to use the include snippet instead?
    Andy Wilkinson
    @wilkinsona
    The two don't know about each other so you'll need to include the individual snippets