Sort schema properties?

[luchsamapparat]

First of all, great project! It helped me a lot while cleaning up a large, chaotic OpenAPI spec.

One thing I was wondering, is it also possible to sort components/schemas alphabetically?

before

components:
  schemas:
    UserDto:
      ...
    PostDto:
      ...
    RoleDto:
      ...

after

components:
  schemas:
    PostDto:
      ...
    RoleDto:
      ...
    UserDto:
      ...

[thim81]

hi @luchsamapparat

If I'm not mistaken, there is support for sorting the properties by alphabet, by using --sortComponentsFile.
I will have to create a little POC to see if my memory is correct, since it has been while that I had to use this.
As soon as I find some spare time, I'll give it spin to verify if --sortComponentsFile is the option to use OR if you have time, you can give it a try.

[luchsamapparat]

I saw that, but wasn't sure how to use it 🤔

[thim81]

I have to agree that the documentation can be improved on how to use it.
By defining which elements that should be sorted, the CLI will sort the elements alphabetically.

I created tests to guard the functionality but also to have examples
Perhaps you can already have a look at the tests:
https://github.com/thim81/openapi-format/tree/main/test/json-sort-request-params
https://github.com/thim81/openapi-format/tree/main/test/yaml-sort-components

[thim81]

hi @luchsamapparat

The --sortComponents works only on the level of the component elements, it does not sort the properties in the elements.

example:

components:
  schemas:
    UserDto:
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string
    AccountDto:
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string

Becomes:

components:
  schemas:
    AccountDto:
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string
    UserDto:
      type: object
      properties:
        lastName:
          type: string
        firstName:
          type: string

[thim81]

It is a valuable sorting capability, so I'll look into it to make it a feature.

The challenging part will be the "configuration" name, how to configure the behaviour.

[luchsamapparat]

Oh! I thought that the sortComponentsFile defines the order of the elements below components (e.g. schemas, parameters, headers), not the elements within them.

So running npx openapi-format spec.yaml -o spec-formatted.yaml --sortComponentsFile componentSort.json with ["schemas"] in the JSON file does exactly what I was looking for.

Thanks for clearing that up!

As a side note: we noticed that sorting the properties (lastName, firstName) is actually tricky because that may for example change the order of constructor parameters in some code generators (e.g. new AccountDto(lastName, firstName)). If, like in this example, both parameters have the same type, changing the order might cause bugs that are hard to catch.

[luchsamapparat]

Thank you!

[thim81]

While your question is answered, would you find it useful to have the option to sort only the schema Component properties?
like: --sortComponentsProps Sort properties within schema components alphabetically

And/or probably have control to define which elements to sort (parameters, responses, schemas, ...)