Provide a mechanism to escape characters that break Asciidoctor and Markdown formatting

[varpa89]

I have a field with validation pattern like this

@Pattern(regexp = "^$|^[0-9]{12}$")
private String inn;

When I generate the documentation for request-fields with ConstrainedFields I have this output:

|inn
|String
|ИНН
|Must match the regular expression '^$|^[0-9]{12}$'

As you can see there is '|' symbol which breaks the layout from this

ext.springRestDocsVersion = '1.1.0.RC1'

[andysworkshop]

I've also hit this one. Easy to reproduce.

[wilkinsona]

A workaround is to escape the | in your test before you set the attribute on the descriptor. REST Docs should really automatically apply any necessary escaping at rendering time, though.

[wilkinsona]

Providing some out-of-the-box configuration of an Escaper looks to be the most elegant way to implement this.

[wilkinsona]

Asciidoctor's straightforward. | can always be replaced with {vbar} and it'll do the right thing.

As ever, Markdown is more complicated. | messes up tables, but only if it isn't within back ticks. When it's not, and only when it's not, within back ticks it can be replaced with |. If it's replaced when it's within backticks you end up with the literal | rather than |. Without getting into parsing the Markdown (which I really don't want to do), it's impossible to know for certain when a | needs to be replaced and when it does not.

I think Markdown's limitations can be avoided by changing the message for the @Pattern constraint to enclose the regular expression in backticks. That'll work for Markdown without adversely affecting Asciidoctor. Arguably, it'll also make the pattern easier to read (see #230).

[wilkinsona]

I spoke to soon. Always replacing | with {vbar} in Asciidoctor breaks the HTTPie snippet which uses |. Using {vbar}, the HTML ends up containing something like this:

$ echo 'content' {vbar} http POST 'http://localhost:8080/' 'Accept:application/json'

When it should be:

$ echo 'content' | http POST 'http://localhost:8080/' 'Accept:application/json'

Looks like it's going to be necessary to provide a JMustache lambda that can then be used in the templates for table cell content where escaping is definitely required.

[varpa89]

Do I need fix template or another code after upgrade to 1.1.0.RELEASE?
Template

|===

|Path|Type|Description|Constraints

{{#fields}}
|{{path}}
|{{type}}
|{{description}}
|{{constraints}}

{{/fields}}
|===

I still have the same output

|inn
|String
|ИНН
|Must match the regular expression '^$|^[0-9]{12}$'