Request and Response Capture

It helps in understanding a REST API if there are clearly defined scenarios. Showing examples of requests used and responses received makes your documentation less abstract.Instead of manually copy-and-pasting the responses back to your documentation, consider running tests and automatically capturing the relevant artifacts.

WebTau

https://testingisdocumenting.org/webtau/REST/getting-started WebTau is a framework to write, run, and capture REST tests artifacts.The bare minimum test in WebTau looks like this: package rest import static org.testingisdocumenting.webtau.WebTauGroovyDsl.* scenario("simple get") { http.get("/weather") { temperature.should == 88 } }

Capture REST Artifacts

To capture artifacts use http.doc.capture package 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']) { return id } http.doc.capture('employee-post') http.get("/employee/$id") { firstName.should == 'FN' lastName.should == 'LN' } http.doc.capture('employee-get') // capture previous HTTP call as <docDir>/employee-get } Captured artifact is a JSON file that looks like this: { "method": "GET", "url": "http://localhost:8180/employee/id-generated-2", "responseType": "application/json", "responseBody": "{\"firstName\":\"FN\",\"lastName\":\"LN\"}\n", "responseBodyChecks": { "failedPaths": [], "passedPaths": [ "root.firstName", "root.lastName" ] } }

Document REST Calls

Once the artifact is captured, include it for documentation with the rest-test plugin. :include-rest-test: REST/employee-get.json The result looks like:or:Note: all the asserted values will be automatically highlighted for your users to help you bring their attention to values of interest.