Feature Request: Provide a visual way to compare example diffs

[skyellin]

Is your feature request related to a problem? Please describe.
When discussing proposed contract changes, it can be very useful to visualize the differences in the examples. This provides a more intuitive way of understanding the changes than does comparing schema differences one by one.

Currently, when viewing diffs in text or html format, the example diffs remove all structure and indentation. Diffs are presented simply as long lines of text such as:

 - Examples changed
       - Modified example: successfulResponse
           - Value changed from map[. . . ] to map[. . . ]

It's very challenging if not impossible to make sense of this, when dealing with large, nested, request and response examples.

Describe the solution you'd like
At a minimum, the examples should be reproduced without removing formatting (preserving line breaks and indentation). In the future, color coding could be added to highlight the changes.

[reuvenharrison]

Hi @skyellin
I would recommend to check the changelog output (example below), it is much easier to understand than the low-level diff.
Could you please share your feedback:

• Does the changelog output provide sufficient context?
• Do you perhaps want to see the changes within the context of the original json/yaml file, and if so, could you explain the use-case?

[skyellin]

I'm looking specifically for a way to compare examples, rather than the schemas themselves. The changelog command you suggested does not compare examples at all, while the diff command produces diffs that are completely unreadable, due to the fact that json is displayed all on a single line, without any line breaks or indentation.

As for why I'd like to have diffs of examples, this is because it can provide an easier way for humans to get an overview of API changes, because they can visually compare two json objects and quickly see the difference. This is especially useful when the structure of these objects changes in subtle ways. For example, consider the following two example responses from a fake flight booking API:

I don't believe that oasdiff currently provides any reasonable way for a human to view such differences, because the json output in general is not very human readable, and the text output seems to remove all formatting from the examples.

[reuvenharrison]

Thanks for the clarification.
We're quite busy now with various tasks to improve oasdiff but we can definitely consider this enhancement ,meanwhile I'd be happy to learn more about your use case.
Please join our slack community and let's discuss there: https://join.slack.com/t/oasdiff/shared_invite/zt-1wvo7wois-ttncNBmyjyRXqBzyg~P6oA

Thanks,
Reuven