Skip to main content

Typed doc-string parameters

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.

Inside the fences you get JSON's own editor: type an opening bracket and it closes itself, the matching pair highlights, and closing quotes type over rather than double — while SpecBinder still passes the whole thing through as a String.

Folding​

Each doc string body folds to a single line. Whether doc strings start folded when the file opens is one setting — Doc strings under Fold on open in Settings → Tools → SpecBinder → Editor — and it applies to every doc string alike, typed or plain. Folding a doc string never hides the step below it.

One Doc strings box under Fold on open decides whether doc strings open folded — every doc string in the file, typed or plain.

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 doc-string content as it is — though the fences move to their correct level, and a body line starting left of them is pulled across with them. A doc string with no content type, or one whose language has no formatter, is treated this way even when you select it.

Select the content between the fences and Reformat Code lays it out by JSON's own rules — because the fence says json, not because SpecBinder treats it as anything but a String. With nothing selected, the same command leaves every doc string alone.

Inline previews​

A doc string with the content type image, svg or html holds a picture or a web page rather than plain text, and an encoded image cannot be read as text at all. For these doc strings the plugin can show a preview directly below the doc string: the rendered picture or page appears in the spec file, next to the text it was made from.

Opening a preview​

A doc string of one of those three types gets a grey eye icon in the gutter, beside its opening """. Click it and the rendered content appears below the closing """, with the icon turning green while the preview is open. Click again to close it.

The eye in the gutter beside the opening fence toggles the preview, and turns green while it is open. The picture appears below the closing quotes, with the markup that produced it still on screen above.

What each type shows​

  • image holds the picture base64 encoded. The plugin works the format out from the data itself — PNG, JPEG, GIF, WebP, BMP and SVG are all recognised.
  • svg holds the markup of the drawing, rendered as it stands.
  • html holds a page, rendered as a browser would.
The `html` case, rendered as a browser would: the heading is a heading, the order number is bold, and the table has borders and a filled cell — all under the markup that produced it, in the spec file.