Spring Rest Docs代码段模板被忽略

Question

I am attempting to be able to create custom snippet template for Spring Rest Docs documentation purposes. I have been following the reference guide

My first problem I ran into was in IntelliJ when creating a .snippet file in src/test/resources/org/springframework/restdocs/templates/asciidoctor/path-parameters.snippet as instructed by the guide. IntelliJ registers it as a jShell snippet file which from a quick glance is not the same as a AsciiDoc snippet. So I went into Settings -> Editor -> File Types and changed jShell Snippet from *.snippet to *.snippetOld. I then created a file type called Snippet and put it's pattern as *.snippet. This now fixes the problem that the snippet template is read as a jShell file. So the .snippet template I created no longer gets compile/validation errors.

But now when I run my mockMvc test after deleting the previous existing adoc files. The path-perameters.adoc file which should had used my custom template, if not use the default template , is now not generated at all.

In my mockMvc test I have the following

//Given
RestDocumentationResultHandler document = makeDocument("name-of-method");
document.document(
    pathParameters(//do path parameters)
    requestParameters(
        parameterWithName("Month").description("The month requested").attributes(
        key("type").value("integer"), key("constraints").value("more than 0 & less than 13.")
        ),
        parameterWithName("Year").description("The year requested").attributes(
            key("type").value("integer"), key("constraints").value("more than 1970 and less than current year")
        )
    ),
    responseField(//Do response fields)
);

// When
mvc.perform(get(REQUEST_PATH, USERID)
          .contentType(MediaType.APPLICATION_JSON)
          .param("month", "8")
          .param("year", "2018"))

          // Then
          .andExpect(status().isOk())
          .andDo(document);

And my snippet template is the following:

   |===
   |Parameter|Description|Type|Constraints

   |{{parameter}}
   |{{description}}
   |{{type}}
   |{{constraints}}

Could somebody point out what I've done wrong/different from the reference guide and how I could fix it to have my template working?

Answer 1

I suspect the reason you did not get output is that you confused path-parameters with request-parameters . Your documentation config specifies request parameters, but you customized path-parameters template

Here is the complete list of snippet templates:

• curl-request.snippet
• http-request.snippet
• http-response.snippet
• httpie-request.snippet
• links.snippet
• path-parameters.snippet
• request-body.snippet
• request-fields.snippet
• request-headers.snippet
• request-parameters.snippet
• request-part-body.snippet
• request-part-fields.snippet
• request-parts.snippet
• response-body.snippet
• response-fields.snippet
• response-headers.snippet

Source:

• https://github.com/spring-projects/spring-restdocs/tree/master/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor