Remove pretty print in example

[Somebody25]

Hello!

I would like to have a human-readable documentation with asciidoctor and a machine-readable documentation with this project. Is there a possibility to disable or un-pretty-print the JSON only for the resource.json?

I know of the possibility of Preprocessor but with this, I can only control both versions of the documentation.

For now, the example in the resource.json and the resulting .yml is riddled with escape and whitespace characters and when imported in postman, it's also shown there. It is impossible to use postman with the imported documentation, without removing these control elements beforehand. This is also shown in the README.md

[ozscheyge]

Hey @Somebody25 ,

a pretty-printed JSON is still machine-readable, is it? :) Do you need minimized file sizes?

I cannot reproduce your postman issue: When I use the postman gradle plugin to generate a postman collection, import it into postman, I have fine example requests and do not need to unescape things.

[m-schroeer]

Hi,

I'm not sure about the original question, but I think his link to the README.md and reference to escape and whitespace characters is related to the following line in the resource.json file:

"example" : "{\n "total" : 0,\n "products" : [ ],\n "_links" : {\n "self" : {\n "href" : "http://localhost:8080/carts/4"\n },\n "order" : {\n "href" : "http://localhost:8080/carts/4/order"\n }\n }\n}"

I've encountered an issue with this as well (note: I'm using the referenced maven plugin from BerkleyTechnologyServices).

The escaped and whitespace characters from the resource.json are included 1:1 in the final openapi file which results in the following rendering of the redoc html file.

instead of:

The result would be:

This behaviour is partly (the \n) originated in the pretty print configuration, for example in an application.properties file or similar:

spring.jackson.serialization.indent_output=true

But still, if the pretty print configuration is not used, there are escaped quotation marks that will result in poorly rendered response samples (I have not tested this for request samples).

The surrounding quotation marks seem to take role in this as well.

If I remove the escaping characters (\" -> ") and the surrounding quotation marks manually before calling redoc-cli everything is rendered as expected (see second image).

---

These were just my two cents on this topic. Maybe I completely misunderstood @Somebody25 's issue or I'm getting any configuration (or encoding?) wrong which results in my presented observations.

Best regards

EDITED: Typo

[ozscheyge]

Thanks for the input @m-schroeer ! You mentioned redoc, so this might be similar: https://github.com/ePages-de/restdocs-api-spec/issues/111 (where the OpenAPI 2 yaml generator apparently doesn't rendered the examples correctly as object but as string)?

Could you be more specific, which gradle plugin (OpenAPI 2? OpenAPI 3?) you are using to generate the target format?

I see no urgent need to fix this since we still generate valid JSON according to OpenAPI 2/OpenAPI 3 specs. As you pointed out, the OpenAPI file could be pre-processed before feeding it into redoc.

[thugcee]

I have exactly the same problem as @m-schroeer and I'm using OpenAPI3. JSON payloads are displayed as escaped strings in ReDoc and Postman (import OpenApi3 YAML file).

[m-schroeer]

You mentioned redoc, so this might be similar: #111

This seems to be same issue for me. Maybe from different starting points, but with the same resulting issue. After reading #111 I am not sure if their starting point of the problem is pretty-print.

I am not in depth into it right now, but at some point something should be done. I am just not sure where this point is. Fact is, if one is using pretty-print(maybe by using spring.jackson.serialization.indent_output=true in application.properties) which is quite normal and should be possible, it is impossible to get the request/response rendered as expected (string vs. object).

[ozscheyge]

Have you tried using the Postman gradle-plugin, generating the Postman Collection and importing this instead, @thugcee ? I haven't used Postman's OpenAPI 3 YAML import yet, but using the Postman format may suffice as a workaround.

[thugcee]

Have you tried using the Postman gradle-plugin, generating the Postman Collection and importing this instead, @thugcee ?

Export to the Postman's Collection format is OK. example's string value in "unescaped" by Postman because this is how Postman stores results in its native format. You just have to click on every req/resp body and change language from plain text to JSON. This could be avoided by adding

"_postman_previewlanguage": "json"

in a response, on the same level where a body element is in a collection.

But unfortunately I'm not using Postman but ReDoc (actually my team uses it). I've tested Postman just to check if the problem is in ReDoc only and it's not.

So it looks like tools are expecting an YAML's "object", not a string, in Media Type Object's value field for content type application/json.

[thugcee]

Here is a quick fix for OpenAPI3 YAML files produced by ePages-de/restdocs-api-spec:

#!/usr/bin/env python3
import sys
import yaml
import json

def fix_examples(res: dict):
    for key, value in res.items():
        if isinstance(value, dict):
            fix_examples(value)
        if key == "application/json":
            for example_name, content in value["examples"].items():
                try:
                    content["value"] = json.loads(content["value"])
                except:
                    pass

with open(sys.argv[1], "r") as api_file:
    res = yaml.safe_load(api_file)
    fix_examples(res)
    print(yaml.dump(res))

Use it like this:

$ ./fix-openapi-yaml.py build/api-spec/openapi3.yaml >openapi-fixed.yaml && redoc-cli bundle openapi-fixed.yaml