Reverse order of properties <paths> and <components> in generated document may avoid display problems

[StenCalDabran]

I'm submitting a...

[ ] Regression 
[x] Bug report
[x] Feature request
[ ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

The generated OpenApi Document currently may be produced in a way where the property paths comes after the property components. While this, to my understanding, does not infringe the specification, it seems to lead to a tenacious bug when used as input for the swagger-ui.
The issue (swagger-api/swagger-ui#3325) regarding recursive rendering goes several years back. Would a behavior change be possible, even though the underlying problem is on their side (I did not know if I should classify this as a feature request or a bug report)?

Expected behavior

Have an interaction of swagger-ui and nestjs/swagger which produces an error-free API experience.

Minimal reproduction of the problem with instructions

I created a sandbox to illustrate the problem: expand the test endpoint -> switch to the tab "schema" -> fully expand the faulty outer type

The used generated OpenApi spec document looks like this:

{
  "openapi": "3.0.0",
  "info": {
    "title": "",
    "description": "",
    "version": "1.0.0",
    "contact": {}
  },
  "tags": [],
  "servers": [],
  "components": {
    "schemas": {
      "InnerType": {
        "type": "object",
        "properties": {
          "innerProperty": {
            "type": "number"
          },
          "innerPropertyWithDescription": {
            "type": "number",
            "description": "Inner description works."
          }
        },
        "required": ["innerProperty", "innerPropertyWithDescription"]
      },
      "OuterTypeWithDescription": {
        "type": "object",
        "properties": {
          "secondLevel": {
            "description": "Second Level level is faulty, it shows only this description instead of the InnerType.",
            "allOf": [
              {
                "$ref": "#/components/schemas/InnerType"
              }
            ]
          }
        },
        "required": ["secondLevel"]
      },
      "OuterTypeWithoutDescription": {
        "type": "object",
        "properties": {
          "secondLevel": {
            "$ref": "#/components/schemas/InnerType"
          }
        },
        "required": ["secondLevel"]
      },
      "ResponseType": {
        "type": "object",
        "properties": {
          "innerType": {
            "description": "First level works.",
            "allOf": [
              {
                "$ref": "#/components/schemas/InnerType"
              }
            ]
          },
          "faultyOuterType": {
            "description": "Outer description works.",
            "allOf": [
              {
                "$ref": "#/components/schemas/OuterTypeWithDescription"
              }
            ]
          },
          "workingOuterType": {
            "description": "Outer description works.",
            "allOf": [
              {
                "$ref": "#/components/schemas/OuterTypeWithoutDescription"
              }
            ]
          }
        },
        "required": ["innerType", "faultyOuterType", "workingOuterType"]
      }
    }
  },
  "paths": {
    "/test": {
      "get": {
        "operationId": "AppController_test",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Response description works.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseType"
                }
              }
            }
          }
        }
      }
    }
  }
}

If you check it in the swagger editor (https://editor.swagger.io/), you can see that the problem only exists as long as the paths property comes after the components property - everything works fine the other way around (thanks to @vanDarg for pointing this out).

What is the motivation / use case for changing the behavior?

A hopefully rather easy change avoids a tenacious bug on swagger-ui side.

Environment

Nest version: 7.6.15
nestjs/swagger version: 4.8.0

[kamilmysliwiec]

Would you like to create a PR for this issue?

[StenCalDabran]

Would you like to create a PR for this issue?

I will at least try 🙂