3

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?

Guillaume S
  • 1,462
  • 2
  • 19
  • 31
shirafuno
  • 387
  • 3
  • 9
  • 24
  • I can't tell what's happening from the description that you've provided. Can you update your question with a [minimal, complete, and verifiable example](/help/mcve)? – Andy Wilkinson Sep 03 '18 at 12:57
  • It would definitely help to see a full example since there's a lot going on. One thing I noticed right away is that parameter(s) is usually the name for the collection, not the field. Did you mean to loop over the collection and use `{{name}}` for that cell value instead? Also, you talked about a custom template for the path parameters, but the example is for request parameters. Was that intentional or could the file name be the problem? – jstrater Oct 05 '18 at 19:17

1 Answers1

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:

kaliatech
  • 17,579
  • 5
  • 72
  • 84