Restdocs Tool Export

Generates AsciiDoc snippets via Spring Restdocs that are exports for Insomnia or Postman that can be download and imported.

Artifact Version

com.github.buckle:restdocs-tool-export:0.0.4-RELEASE

Test Configuration

ToolExportSnippet needs to be initialized and then called for each documentation request. Once integration tests have run include the generated Insomnia/Postman snippet in your AsciiDoc file. The generated link contains an export of the included tool. A very simple example can be seen in the integration test RestDocsIT.

Initialize

  @Value("${spring.application.name}") protected String applicationName;

  @BeforeEach
  void setUp() throws Exception {
    ToolExportSnippet.initInstance(applicationName, ToolHandlers.INSOMNIA, ToolHandlers.POSTMAN);
    ToolExportSnippet.setProperty(HOST_VARIABLE_ENABLED, true);
  }

Document

    document("request-test",
             pathParameters(parameterWithName("key")
                                       .description("Test path parameter")
             ),
             responseFields(fieldWithPath("responseField")
                                       .description("Test response field")),
             ToolExportSnippet.getInstance()
    );

ADoc Include

== Downloads
Insomnia
include::{snippets}/insomnia-download/insomnia.adoc[]

Postman
include::{snippets}/postman-download/postman.adoc[]

Host Variable

By default, host will be exported as its own variable, a property can be used to disable it

    ToolExportSnippet.setProperty(HOST_VARIABLE_ENABLED, false);

Variables

Anywhere <<anystring>> appears in the request, a variable will be created in the exports

     mockMvc.perform(post("/post/test/{pathVariable}?param1={queryParam}", "<<path-variable>>", "<<query-param-variable>>")
        .contentType(MediaType.APPLICATION_JSON)
        .header("X-Key", "<<header-variable>>")
        .content(objectMapper.writeValueAsBytes(postData))
        .secure(true))
        .andExpect(status().isOk())
        .andDo(document(...));

Header Variables

When << can't be included in the request directly, you can update values using a preprocessor like HeaderVariablePreprocessor

replaceHeaderValueWithVariable() will change the value of any matching headers to a variable (ex. x_key_header).

    document("request-test",
             preprocessRequest(
              replaceHeaderValueWithVariable("X-Key")),
              pathParameters(parameterWithName("key")
                                       .description("Test path parameter")
             ),
             ToolExportSnippet.getInstance()
    );

replaceHeaderValueWithVariable can be applied to all requests by customizing mockmvc Use a preprocessor like modifyHeaders().add() if you want to add this header to every request, otherwise it will just replace the values when the header is present

  @Autowired protected WebApplicationContext context;
  
  MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)...
    .operationPreprocessors().withRequestDefaults(
        modifyHeaders().add("x-api-key", ""),
        replaceHeaderValueWithVariable("x-api-key")))
    .build();