Sort arrays and objects in generated swagger file

[vincentvanderweele]

Sorting

• I'm submitting a ...

  • [ ] bug report
  • [X] feature request
  • [ ] support request

• I confirm that I

  • [X] used the search to make sure that a similar issue hasn't already been submit

Expected Behavior

We check the generated swagger spec into source control because it is a convenient way to glance over API changes in pull requests. However, currently the generated spec is not very git-friendly. Small changes in code (a controller importing a file it didn't before) can completely shuffle the generated spec.

It would be nice if the generated spec was stable between builds. Sorting everything seems like the easiest way to make that work.

Current Behavior

I'm not sure what exactly the current behavior is. I suppose the order depends on Typescript emitting the types?

Possible Solution

I haven't checked the code but it shouldn't be too hard to sort everything before writing it to file.

Steps to Reproduce

Context (Environment)

Version of the library: 3.8.0 Version of NodeJS: v15.14.0

• Confirm you were using yarn not npm: [X]

Detailed Description

See possible solution. I could create a PR if this is something worth doing.

Breaking change?

It shouldn't be, unless users depend on the order of arrays and objects in the spec, which I highly doubt. Object and array order in the swagger spec should have no semantic value.

[WoH]

I personally think of the spec as a build artifact, but that shouldn't prevent you from treating it differently. I assume the issue is w/ regards to the paths, likely with the components as well?

[vincentvanderweele]

Yes @WoH this is mainly about definitions and paths. Probably also about responses and security definitions, although they don't change so often.

I definitely agree with you that the spec is a build artifact and since order of definitions and paths has no semantics, it doesn't need to be Tsoa's responsibility to output them in stable order. So if this is not something you want in Tsoa, that would make sense too and I will look into some post-processing options instead.

[vincentvanderweele]

I decided to go for a separate tool after all. I think you are correct that sorting the spec does not belong in tsoa. Feel free to close this issue.

For interested future visitors, I now use json-sort-cli but I'm sure there are similar tools out there.

With json-sort-cli building the spec now becomes:

tsoa spec-and-routes && jsonsort swagger.json --arrays

[wsmckenz]

FWIW, I was playing with the same problem today, and it looks like you can solve this by putting a high level list of tags in order in your tsoa.json, under the spec. This list's order will be respected by the swagger UI.

    "spec": {
      "name": "Quilt API",
      "tags": [
        {"name" : "PortfolioCompany"},
        {"name" : "CapitalCall"},
        {"name" : "Distribution"},
        {"name" : "Commitment"},
        {"name" : "Valuation"},
        {"name" : "Integration"}
      ],