Re-usable patterns

Let's consider a chat REST API example where we want to display a sample input, example code snippet, and sample output. Here how documentation may look like.Use to send a new message http.post("/messages", [message: "Hello all"]) { id.should == "mid1" } This is the source to render the layout above :include-groovy: org/testingisdocumenting/testing/examples/restapi/WebTauRestAPIGroovyTest.groovy { title: "POST messages", entry: "postMessages", bodyOnly: true, excludeRegexp: "http.doc" } ```columns left: :include-json: chat-post-messages/request.json { title: "POST /messages request" } right: :include-json: chat-post-messages/response.json { title: "POST /messages response", highlightValueFile: "chat-post-messages/paths.json" } ``` Note: request and response were automatically captured using synergy-with-testing/REST-API WebTau testing framework.We need to document other methods as well, and as you can imagine, the repetition will take place.

Extract A Pattern

Let's move a block we plan to repeat into a separate file and replace hardcoding of entries like post with placeholders. Znai uses the https://freemarker.apache.org FreeMarker template engine. :include-groovy: org/testingisdocumenting/testing/examples/restapi/WebTauRestAPIGroovyTest.groovy { title: "${method?upper_case} messages", entry: "${method}Messages", bodyOnly: true, excludeRegexp: "http.doc" } ```columns left: :include-json: chat-${method}-messages/request.json { title: "${method?upper_case} /messages request" } right: :include-json: chat-${method}-messages/response.json { title: "${method?upper_case} /messages response", highlightValueFile: "chat-post-messages/paths.json" } ```

Use A Pattern

:include-template: templates/messages-http-call.md {method: "put"} http.post("/messages/mid1", [message: "Hello all!"]) { status.should == "SUCCESS" }