The order of the directive changes between versions of the dependent package

[cou929]

I've found an unexpected behavior that the output was different even if the input files are identical and swagger-cli version is also the same. Is this behavior intentional?

How to reproduce

• definition files are like this:
  • https://gist.github.com/cou929/9d0402301d9be9aefb6ce3a5bac0d3b4
• generate a combined file by this command:

swagger-cli bundle -o ./result.yaml -t yaml ./base.yaml --dereference

• different outputs are generated if a version of installed @apidevtools/swagger-parser is differ

npm install -g @apidevtools/swagger-cli @apidevtools/[email protected]
swagger-cli --version  # => 4.0.4
swagger-cli bundle -o ./out.10.0.3.yaml -t yaml ./base.yaml --dereference

npm install -g @apidevtools/swagger-cli @apidevtools/[email protected]
swagger-cli --version  # => 4.0.4
swagger-cli bundle -o ./out.10.1.0.yaml -t yaml ./base.yaml --dereference

diff -u out.10.0.3.yaml out.10.1.0.yaml

--- out.10.0.3.yaml     2023-02-22 01:38:29.174884945 +0900
+++ out.10.1.0.yaml     2023-02-22 01:38:45.803131147 +0900
@@ -31,6 +31,7 @@
           content:
             application/json:
               schema:
+                description: the order of this description directive changes between versions
                 type: object
                 required:
                   - test
@@ -38,4 +39,3 @@
                   test:
                     type: integer
                     example: 1
-                description: the order of this description directive changes between versions

Expected behavior

The same output is generated if the input and swagger-cli version are identical.

Such situations can occur, for example, in the following cases: when a new member joins our team, and runs npm install -g @apidevtools/swagger-cli @4.0.4, this member's machine may have a different version of swagger-parser. If so, there will be differences in the files generated by the new member and the existing member even if the version of swagger-cli is fixed.

This feels counter-intuitive to me. Especially if we're committing the generated files to git, the differences in the output cause annoying diff.

notes

• I'm not sure of the exact cause but this difference seems to come from this block of json-schema-ref-parser
• The version of json-schema-ref-parser is fixed in this commit but I couldn't find out more details of this change