Diff / merge OpenAPI specifications
I am part of a team that develops APIs and we use OpenAPI 3 to specify the API's contracts/interfaces. Of course we have the .json files under source control.
The challenge is to have different developers work on the API specs concurrently in different branches. The merge facilities in Idea do not seem to ignore the order of the fields/components in the spec when comparing, resulting in duplicate paths and schemas in the OpenAPI file.
I am currently using the plugin json-diff and use it on two clones of the repo, for example one with the main branch and the other with the feature branch. And do a manual merge of the .json files from these two clones.
Is there a way to use this plugin for GIT-merges instead? Or is there a more intelligent way to merge .json files in Idea?
请先登录再写评论。
Do I understand correctly that you are doing a merge of json files without Git interaction? It's not a merge during some git operations rather than cross-repository merge?
Perhaps you are looking for something like this:
https://youtrack.jetbrains.com/issue/IDEA-233541/Swagger-Diff-integration
No, I think I didn't explain myself correctly.
I'm on a project developing a microservice that exposes some API. Different developers work on the implementation of different APIs, but they are all part of the same OpenAPI 3 spec.
When merging the OpenAPI spec, in json format, the diff is a literal diff, what I mean is that it looks line by line whether it detects a difference and then proposes to merge one way or the other.
What I am looking for is a more intelligent diff, one that sees that in one OpenAPI spec a definition is missing, compared to the other spec.
For example, I have a response defined in the OpenAPI json file to return a 401 and a 404. Now my colleague added a 403 and defined it between the 401 and 404 definitions. The current diff will not see that the 403 block is missing in one and proposes to merge it in its entirety into the file.
Similarly, when I have two OpenAPI files that are the same, but the order in which the response blocks are defined is different, e.g. 401-403-404 vs 403-401-404, the diff doesn't see that the files are the same, just differently ordered.
In other words, the merge capabilities of Idea CE for json files is not very useful and I have to revert to for example the json-diff plugin and merge two files on my filesystem. The way I do this, is by cloning the repo twice, and checkout in each one branch of the two I have a pull request on. Then I use json-diff in the clone to which I want to merge and open as second file the json file from the other clone using json-diff. This works, but it is cumbersome.
Thank you, the idea is much more clear now.
In general, you can vote for
https://youtrack.jetbrains.com/issue/IDEA-273646/Diff-view:-support-formatting-for-JSON-files,
but there is no ETA for this ticket for now.
From the other side, it should not be difficult to expand on top of `json-diff` plugin approach with the merge.
Ex: when facing JSON files - convert left/base/right contents into this 'canonical form' and merge like this.
This should produce much better results than raw "text diff" (with caveat of merge result being in 'canonical form', which might vastly differ from file's current layout).
If you'd like some tips on implementation or help with plugin development, feel free to ask here.