Request and response samples are quoted in Redoc about restdocs-api-spec

[ozscheyge]

Afaics, we are rendering correct OpenAPI 2, but redoc would like to have the yaml example string in a certain format/syntax?

[arhohuttunen]

I seem to have forgotten to answer to this. The problem is not that the example has wrong string format, but that it is a string, since using |- denotes a string.

examples:
  application/json: |-
    {
      "foo": "bar"
    }

This cannot be rendered as an object, since it’s not. It is a string representation of the object we need.

The correct way to represent the example would be to use an actual object:

examples:
  application/json:
    {
      ”foo”: ”bar”
    }

Reference: https://swagger.io/docs/specification/2-0/adding-examples/

The same happens with JSON output as well, because the example is wrapped in quotes. What we ended up doing to work around this was to parse the output ourselves to get rid of the extra characters in examples.

[kiftio]

Fyi - after upgrading to spring boot 2.3.x, and transitively to jackson 2.11.0, this is now a bit tricker to work around.

Where we used to get this output:

  |-
  {
      "a":"b",
      "c":"d"
  }

We now get:

"{\n    \"a\":\"b\",\n    \"c\":\"d\"\n}"

So it's no longer just a case of removing |- to get redoc to display unquoted request / response samples.

I think it's potentially due to this change - FasterXML/jackson-dataformats-text@c41a621#diff-6eedc03a68a69933c763e674f2d7c42f

[thugcee]

So it's no longer just a case of removing |- to get redoc to display unquoted request / response samples.

Try this workaround: #109 (comment)

[ozscheyge]

Based on kiftio's findings and https://yaml.org/spec/1.2/spec.html#id2788859, I'd say: quoting of the example is working as intended by YAML spec and I'd close this.

thugcee provided a nice workaround for redoc users.