Open API helps to define a formal API specification. And real examples of request/response helps to clarify. Instead of manually copy-and-pasting the responses to your documentation, consider running tests and automatically capturing the relevant artifacts.

WebTau (short for web test automation) is a testing API, command line tool and a framework to write unit, integration and end-to-end tests. Test across REST-API, Graph QL, Browser, Database, CLI and Business Logic with consistent set of matchers and concepts. Here is an example of REST API test with test artifacts capture scenario("create and access employee") { 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 }

Documentation pipeline can look like build Build deploy Deploy testrun Test Run documentation Documentation Build # 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", highlightValueFile: "doc-artifacts/employee-post/paths.json" } ```

Request Responses 200 201 post /employee Create new employee Create a new employee, by sending details and get back the id of a newly created employee