Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    wykaPedia
    @wykapedia
    
    
    
    
    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
            .apply(documentationConfiguration(this.restDocumentation).uris()
                    .withScheme("https")
                    .withHost("example.com")
                    .withPort(443))
            .build();
    Gabriel Claudiu Georgiu
    @ClaudiuGeorgiu

    Hello, is it possible to generate both markdown and asciidoc snippets at the same time? I tried with the following code but it doesn't work like I would like (only markdown/asciidoc documentation gets generated but not both at the same time).

    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                    .apply(documentationConfiguration(this.restDocumentation)
                            .snippets().withTemplateFormat(TemplateFormats.asciidoctor()).and()
                            .snippets().withTemplateFormat(TemplateFormats.markdown()))
                    .build();

    Thanks in advance.

    Andy Wilkinson
    @wilkinsona

    @ClaudiuGeorgiu I haven't heard of that requirement before, but I think it might be possible if you apply REST Docs twice when you're building the MockMvc instance. Something like this:

    MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
            .apply(documentationConfiguration(this.restDocumentation).snippets()
                    .withTemplateFormat(TemplateFormats.asciidoctor()))
            .apply(documentationConfiguration(this.restDocumentation).snippets()
                    .withTemplateFormat(TemplateFormats.markdown()))
            .build();

    I think that's worth a try, although it may break in unexpected ways as I don't think it's been tried before.

    Gabriel Claudiu Georgiu
    @ClaudiuGeorgiu
    @wilkinsona Thank you, I have tried your suggestion but unfortunately it doesn't work: the second apply(...) overrides the first one, so I'm only getting markdown documentation (or asciidoc, if I swap the instructions). My use case is the following: I'm using swagger2markup to generate the documentation and REST Docs to generate the code snippets; I want to generate the markdown documentation to be used as a README in the repository, while the asciidoc documentation is needed to generate the final pdf/html. For now I have 2 options:
    • generate everything in asciidoc and then convert it to markdown (I would prefer to avoid this solution since both swagger2markup and REST Docs support markdown output)
    • run the tests twice, once using asciidoc as output and the second time using markdown (I would like to avoid this as well since it adds unnecessary overhead)
    Andy Wilkinson
    @wilkinsona

    Ah, yeah. Of course. That won't stop the attribute from the request that holds the configuration from being overwritten. Ok. I think you can stop that from happening if you do something like this:

    DefaultMockMvcBuilder builder = MockMvcBuilders.webAppContextSetup(this.context);
    RequestPostProcessor asciidoc = documentationConfiguration(this.restDocumentation)
            .snippets().withTemplateFormat(TemplateFormats.asciidoctor())
            .beforeMockMvcCreated(builder, this.context);
    RequestPostProcessor markdown = documentationConfiguration(this.restDocumentation)
            .snippets().withTemplateFormat(TemplateFormats.markdown())
            .beforeMockMvcCreated(builder, this.context);
    MockMvc mockMvc = builder.build();
    mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk()).andDo((result) -> {
                asciidoc.postProcessRequest(result.getRequest());
                document("asciidoc-and-markdown").handle(result);
                markdown.postProcessRequest(result.getRequest());
                document("asciidoc-and-markdown").handle(result);
            });

    That seems to work fine for the default snippets anyway. It's undoubtedly a bit of a hack, though. REST Docs hasn't been designed to document the same thing twice.

    Gabriel Claudiu Georgiu
    @ClaudiuGeorgiu
    Thank you @wilkinsona, it works.
    Arun Kumar
    @arumaum
    Hi All , Is there way to customize AutoDocumentation.requestFields() Request field few of the fields need to deleted from api doc but it is required for other purpose how we can achieve
    Andy Wilkinson
    @wilkinsona
    @arumaum AutoDocumentation isn't part of Spring REST Docs itself so I'm not sure if there'll be anyone here who can help.
    Arun Kumar
    @arumaum
    @wilkinsona Thanks for info .
    Liang Zhou
    @lzhoucs
    Hi, I am new to spring-restdocs. I see by default the generated doc(index.html) is bundled inside the jar at /static/docs folder, I wonder how should I server this folder when I launch the springboot app?
    Liang Zhou
    @lzhoucs
    Carlos Adolfo Ortiz Q
    @cortizqgithub
    @wilin
    @wilkinsona Now I continue the question about my HTTP Codes in an Endpoint. From the other channel Spring Boot you pointed me to go to https://docs.spring.io/spring-restdocs/docs/2.0.x/samples/restful-notes/api-guide.html#overview-http-status-codes I will take a look. Thanks.
    Carlos Adolfo Ortiz Q
    @cortizqgithub
    Hi. How do I configure the Rest Docs Asciidoc to generate PDF or ePUB
    Jenn Strater
    @jlstrater
    @cortizqgithub are you using maven or gradle?
    Knut Schleßelmann
    @kschlesselmann
    Are there any samples using the new Asciidoctor 2.1.0 plugin (possibly using the gradle kotlin DSL)? A simple update from 1.5.9.2 breaks my build because the old Asciidoctor Task seems to be deprecated and the new one seems fais with some empty collections error. My setup looks like
    val asciiDoctor = tasks.withType<AsciidoctorTask> {
        inputs.dir(snippetsDir)
    
        dependsOn(test)
    }
    
    tasks.withType<BootJar> {
        launchScript()
    
        dependsOn(asciiDoctor)
    
        from("${asciiDoctor.first().outputDir}/html5") {
            into("static/docs")
        }
    }
    * What went wrong:
    Collection is empty.
    In line 83 … which would be from("${asciiDoctor.first().outputDir}/html5") {
    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!