Use happy paths test scenarios to document your API. Capture requests performed and response received. Use it as part of your documentation. Benefits:No manual copy-pasting of requests/responses Documentation is up-to-date Happy paths API is working as intended

Use http.doc.capture to capture REST API artifacts Groovy package scenarios.rest import static org.testingisdocumenting.webtau.WebTauGroovyDsl.* scenario("extracting id after POST to use inside GET request") { def id = http.post("/employee", [firstName: 'FN', lastName: 'LN']) { id.shouldNot == "" return id } http.doc.capture('employee-post') // capture previous HTTP call into <docDir>/employee-post http.get("/employee/$id") { firstName.should == 'FN' lastName.should == 'LN' } http.doc.capture('employee-get') // capture previous HTTP call into <docDir>/employee-get } Java package com.example.tests.junit5; import org.junit.jupiter.api.Test; import org.testingisdocumenting.webtau.junit5.WebTau; import static org.testingisdocumenting.webtau.WebTauDsl.*; @WebTau public class CustomerDocCaptureTest { @Test public void extractIdAfterPostToUseInsideGetRequest() { var customerPayload = http.json( "firstName", "FN", "lastName", "LN"); int id = http.post("/customers", customerPayload, ((header, body) -> { body.get("id").shouldNot(equal("")); return body.get("id"); })); http.doc.capture("employee-post"); // capture previous HTTP call into <docDir>/employee-post http.get("/customers/" + id, ((header, body) -> { body.get("firstName").should(equal("FN")); body.get("lastName").should(equal("LN")); })); http.doc.capture("employee-get"); // capture previous HTTP call into <docDir>/employee-get } } An employee-get directory will be created containing a number of test artifacts.

Documentation pipeline can look likeExample of using captured artifacts using https://github.com/testingisdocumenting/znai Znai markdown # Create Employee :include-open-api: openapi/api-spec.json {operationId: "createEmployee" } ```columns left: :include-json: doc-artifacts/employee-post/request.json { title: "request payload" } right: :include-json: doc-artifacts/employee-post/response.json { title: "response payload", pathsFile: "doc-artifacts/employee-post/paths.json" } ```

Request Responses 200 201

By default, the directory will be created in the current working directory. To change it add docPath to your webtau.cfg.groovy file. url = "http://localhost:8180" docPath = "doc-artifacts"

A number of artifacts will be created depending on the exact call being captured. Request and response payloads Request bodies are captured in either request.json , request.pdf or request.data depending on the type.Similarly, response bodies are captured in either response.json , response.pdf or response.data . Request and response headers Just like payloads, request and response headers are captured in request.header.txt and response.header.txt respectively. These files contain a header per line with the name and values colon separated. The values are redacted for any potentially sensitive headers. Response body assertions Any assertions you perform on the response body in your scenarios are captured in a paths.json file. This contains an array with the list of paths within the body whose values were asserted. Request URLs The actual request URL is captured in two forms into two different files: request.fullurl.txt - contains the full URL request.url.txt - contains only the part specified in the http call in the scenario /path?a=1&b=text http://localhost:35813/path?a=1&b=text