OpenAPI document generation should emit documents with deterministic structure

[mikekistler]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The OpenAPI document currently generated by .NET has a non-deterministic ordering of certain features such as path items, tag objects, and possibly other elements. This is problematic in situations where the OpenAPI document is generated at build time and committed to source control, because a small change in the app could generate a diff in the OpenAPI document that is simply a reordering of elements.

An example of the problem is [this PR in the eShop project], where the diff of the src/Catalog.API/Catalog.API.json file shows:

>git diff --stat main src/Catalog.API/Catalog.API.json 
 src/Catalog.API/Catalog.API.json | 602 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------------------------------------------
 1 file changed, 306 insertions(+), 296 deletions(-)

but by sorting the files with jq, we can see that the substantive changes are much smaller:

>diff <(git show main:src/Catalog.API/Catalog.API.json | jq --sort-keys .) <(jq --sort-keys . src/Catalog.API/Catalog.API.json) 
379a380,389
>           "400": {
>             "content": {
>               "application/json": {
>                 "schema": {
>                   "$ref": "#/components/schemas/ProblemDetails"
>                 }
>               }
>             },
>             "description": "Bad Request"
>           },
968,970d977
<       "name": "Search"
<     },
<     {
974a982,984
>     },
>     {
>       "name": "Search"

Here only the 400 response is substantive -- the other change is a recording of the tag objects which isn't remedied by the --sort-keys feature of jq.

Describe the solution you'd like

The framework should generate the OpenAPI document with a deterministic structure, such that changes to the app will produce a new document with minimal and only "substantive" changes in the textual diff.

Additional context

No response

[mikekistler]

More information on this: I was able to write a transformer that minimizes the diff of the V1 API document in eShop. The transformer:

• Reorders the Path items to be sorted by path
• Reorders the operations in each Path Item in a fixed order (get, post, put, patch, delete, head, options)
• Reorders the entries of the global tags field to be ordered by tag name.

I'll publish this transformer in my aspnet-transformers-gallery project shortly. Users needing this support can use the transformer until we add the support directly in the framework.

[eerhardt]

I was able to write a transformer that minimizes the diff of the V1 API document in eShop

Hey @mikekistler, I'm seeing diffs in eshop after I build:

Was this issue worked around in dotnet/eshop?

[mikekistler]

@eerhardt Is it possible that this is just line ending difference?

[eerhardt]

It's possible. But eshop has

# Set default behavior to automatically normalize line endings.
###############################################################################
* text=auto

In its .gitattributes file. So if the OpenAPI document generation was writing the file correctly, this diff shouldn't happen.

[mikekistler]

I think the .gitattributes may be enforced on a commit but not necessarily on a diff. Here's what VSCode tells me about the line endings of src/Catalog.API/Catalog.API.json in the main branch of eShop.

Do you see this same thing for the OpenAPI generated by your build?

[captainsafia]

For the original issue, my suspicion still remains that the Asp.Versioning implementation in eShop is related to the root cause here. We have snapshot tests for OpenAPI docs in the repo that have been running for over a year and no non-deterministic ordering issues have appeared there.

In either case, the API in OpenAPI.NET does allow for ordering via transformers in the event this issue reappears.