this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration(this.restDocumentation).uris()
.withScheme("https")
.withHost("example.com")
.withPort(443))
.build();
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.
@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.
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)
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.
http://localhost:8080/docs/index.html works
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.from("${asciiDoctor.first().outputDir}/html5") {
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?
@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.
hello! i've noticed that, for a request with a required request parameter, these two behave differently:
document("{class-name}/{method-name}")- doesn't faildocument("{class-name}/{method-name}", requestParameters())- fails
and I was just wondering if someone could explain what's a reason behind this decision? tnx!
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.
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.
org.springframework.restdocs.mustache.MustacheException$Context: No method or field with name 'defaultValue' on line 8 because not every snippet has those values
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
RouterFunction rather than a @Controller, but the principle's the same on the testing and documentation side.
@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