Always generate yaml/json with the same element order

[kemalizing]

Is your feature request related to a problem? Please describe.
We are using springdoc to generate openapi yaml files from kotlin code (for this feature language doesn't matter, it is the same for java), and also we store the output in our git repo. Whenever we change something in underlying kotlin classes, we re-generate the yaml and create a PR. because there is no guarantee in generated yaml element ordering, even if we change something very small, we have a huge PR for the yaml part.

Describe the solution you'd like
Generate the yaml/json in a way that the ordering is consistent between every generation. This can be achieved by sorting paths, components etc by name while generating the spec.

Describe alternatives you've considered

Additional context

[bnasslahsen]

@kemalizing,

This can be an option. But for the solution you are proposing, can you propose a PR?

[bnasslahsen]

Closed, as no response here.

[kemalizing]

I need to read your source and then find the solution to create a PR for this.. I'll try but I'm not sure when I can create a PR

[jeff-lauterbach-by]

I also have a need for this in order to upload the generated spec to an API Gateway. The generated spec not being consistently ordered which is causing some challenging in our deploiyment pipelines.

I'd be willing to create a PR... but am not familiar with this project source at all yet so any pointers on the code components that might be involved here would help speed this along.

[jeff-lauterbach-by]

I've been digging into this and it seems the ordering of Paths is influenced by the order the Spring detects controllers which can vary by machine/env (for me, I noticed it behaved differently whether I lanched springboot from a zsh or bash shell).

I didn't see a very clean way to order the map of HandlerMethods since each method could have multiple patterns specified.
https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/main/java/org/springdoc/webmvc/api/OpenApiResource.java#L243

I then found some discussion on the swagger-core library that gave an example of adding a mixin to the ObjectMapper to be able to sort properties alphabetically.
swagger-api/swagger-core#3613

As an inital poc, I added a config option to springdoc to support sorting paths and it seems to be working for me to have more stable generated files.

@bnasslahsen and @kemalizing Does this seem like an okay approach? I'm happy to create a PR.

[kemalizing]

That sounds great Jeff, thanks for your efforts!

[jeff-lauterbach-by]

I hit a snag with the mixin approach as Jackson only allows a single mixin per target class and swagger-core is leveraging mixins already. Still looking into this.

[PaulFrmBrn]

Got the same issue.
I've got an integration/component test that checks that OASv3 schema isn't changed from build to build.
My workaround is to use Jackson to compare trees built from string representations.

assertEquals(jacksonObjectMapper.readTree(expected), jacksonObjectMapper.readTree(actual))

Not very smart, but works fine with Json.

[mjustin]

I also am running across this issue in a project, and it's cropping up in two different places.

First, the exact same issue as this one: #857 (comment), with the issue described in the ticket thrown in (#857 (comment)). Namely, the Swagger schema is stored in source control to ensure it's not unexpectedly changing from build to build. When it does change and it's intentional, we copy/paste the generated Swagger into a committed file. However, since the order is not guaranteed, the commit is a mess of unrelated changes, making the actual change non-obvious in a sea of rearrangements.

Second, the Swagger endpoint is being used by another part of the project by the OpenAPI TypeScript Node TypeScript API generator. These files are committed to source control. The ordering of the generated files matches the ordering of Swagger, so reruns end up being generated in a different order. As above, the commit of this code is a mess of unrelated changes, making the actual change non-obvious in a sea of rearrangements.

[mjustin]

Looks like I incorrectly assumed the lack of resolution on this issue meant it was never implemented. This can now be done by setting the springdoc.writer-with-order-by-keys application property to true.