Skip to main content

Typed doc strings

A doc string carries a block of text under a step — a request body, an expected payload, a fragment of markup. Write a content type straight after the opening """ and the IDE stops treating that block as plain text and reads it as the language you named.

Given the response body:
  """json
  {
    "id": 42,
    "status": "ok",
    "items": [
      { "sku": "A-100", "quantity": 2 }
    ]
  }
  """

The recognised types are json, xml, yaml (or yml), html (or xhtml), svg and image (or img). The name is not case-sensitive, so """JSON works as well as """json. A doc string with no content type stays plain text.

The last three carry a document rather than data, so the plugin can also render one: html, svg and image bodies can be shown in a preview panel below the doc string, without leaving the spec file. Refer to Inline previews.

Language-aware editing​

Inside a typed doc string you get that language's editor support: syntax colours, error highlighting, folding of its own structures, and the rest of the IDE's services for it. Writing a larger payload in a spec file is then no harder than writing it in a file of its own.

<A step with a """json doc string, the JSON syntax coloured, and an error highlighted in the body.>

Folding​

Each doc string body folds to a single line, and each content type has its own setting for whether it starts folded when the file opens. So image doc strings can be out of the way by default while plain ones stay open. Folding a doc string never hides the step below it.

<The Element folding section under Settings → Tools → SpecBinder → Editor, with the collapse-on-open checkboxes — one per content type — visible.>

Reformatting the payload​

Select the body and run Reformat Code. The content is formatted by that language's own formatter and re-indented under the opening """, which turns a payload pasted on one line into something readable. This works for json, yaml, html, xhtml, xml and svg.

With nothing selected, Reformat Code formats the spec file and leaves every doc string as it is, so a payload is only ever reformatted when you ask for it. The same is true of a doc string with no content type, or one whose language has no formatter.

<A """json doc string on one long line, and the same doc string after Reformat Code, over several lines and indented under its opening quotes.>