Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deterministic and alphabetical orderding of JSON and YAML output #3613

Closed
wants to merge 3 commits into from
Closed

Deterministic and alphabetical orderding of JSON and YAML output #3613

wants to merge 3 commits into from

Conversation

hiddewie
Copy link
Contributor

@hiddewie hiddewie commented Jul 2, 2020

References:

Problem

When using the Swagger library to generate OpenAPI specifications from source code, the output should be fully deterministic. Running the tool on the same source code should always give the same result. This is not the case at the moment.

Because the output is non-deterministic, the contents will change after running the tool again. This causes problems when the output is committed to a version control system such as Git. Even when not changing the input, a huge diff may be generated because the content of the file has changed.

This PR

This PR contains two parts:

  • There were two parts of the core library that were non deterministic, the reflection access of fields and of methods. These instances in the code have been sorted for determinism.
  • Many parts of the OpenAPI specification are stored in Maps, specifically unordered Maps. This causes problems because the insertion order is ususally the iteration order. This problem has been solved by having the Object mapper (Jackson) sort the output properties.

@a-abella
Copy link

a-abella commented Jul 2, 2020

please build

@swarth100
Copy link

swarth100 commented Aug 6, 2020

I've also been looking into deterministic serialization of the OpenAPI spec and I believe the above changes might not be enough.

Individual classes (such as Schema) could still serialize their fields in a different order.

My current workaround is to acquire Swagger's object mapper and set property ordering for these specific classes:

Json.mapper().addMixIn(Schema.class, AlphabeticallySorted.class);

...

@JsonPropertyOrder(alphabetic = true)
public abstract static class AlphabeticallySorted {}

@hiddewie
Copy link
Contributor Author

@swarth100 That also seems like a good (additional) solution. Could you make a test case with a specification which fails on non-determinism for this PR?

@mariantirlea
Copy link

Hello, I am looking forward to see an updated on this. This feature will really help us because we need a test where the current OpenApi file is compared to a reference file to see if there are any differences (this way we avoid unwanted mistakes in the API)

@frantuma
Copy link
Member

frantuma commented Dec 3, 2020

included and replaced by #3740, see PR comment for details and usage scenarios

@frantuma frantuma closed this Dec 3, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants