I need to store swagger statically-generated api json files in our git repo, to easily track API changes. Similar to this http://petstore.swagger.wordnik.com/api/api-docs/user
I've attached maven plugin https://github.com/kongchen/swagger-maven-plugin
to the project, and it generates *.json files for API. But, the order of api and properties are different from time to time. So the *.json files become modified without any api changes (just different order).
Then I've specified the "position" parameter to the every
@Api,
@ApiOperation
@ApiModelProperty
annotation,
and it's mostly help. but there are some services, that return org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput and javax.ws.rs.core.Response classes, and the properties for that classes are still in random order. So then I've overridden json representation of these classes with /swagger-overriding-models.json
And now it works fine. I just wandering, may be it's not the best way, and there are some other possibilities to have api json files generated in the predictable order, without mess with "position" and model overriding?
Guaranteeing ordering is not that simple. Java's reflection does not guarantee ordering when using reflection - http://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getDeclaredFields--:
The elements in the returned array are not sorted and are not in any particular order.Granted, it will normally return them in the declaration order, but this undocumented and not officially part of the JLS.
Theoretically swagger-core/swagger-maven-plugin could enforce alphabetical ordering, but it is probably even less desirable because in some aspects of the documentation, ordering matters (hence the
"position"attribute).You do raise an interesting point regarding the need - to track API changes. I'd urge you to open an issue on https://github.com/swagger-api/swagger-spec, so we can see if we can either produce a solution for it, either as a form of the spec or a support tool to diff versions of the spec.