$ref renders schema type as any instead of object in modular YAML config

[corock]

Q&A (please complete the following information)

• OS: macOS (Apple Silicon)
• Browser: Chrome
• Version: 129.0.6668.70
• Method of installation: Maven Repository > SpringDoc OpenAPI UI or SpringDoc OpenAPI Starter WebMVC UI
• Swagger-UI version: 5.11.8
• Swagger/OpenAPI version: OpenAPI 3.1

Content & configuration

To reproduce, create a simple file structure in a Spring Boot project with application.yaml, users.yaml (OAS 3.1), and user.yaml (schema file).

application.yaml

springdoc:
  api-docs:
    version: openapi_3_1
  swagger-ui:
    urls:
      - name: users-v1
        url: openapis/users.yaml

resources/static/openapis/users.yaml (path from content root)

openapi: 3.1.0

# (...)

components:
  schemas:
    User:
      # Separate the schema specification into a separate file and reference it using $ref
      $ref: 'components/schemas/users/user.yaml#/components/schemas/User'

resources/static/openapis/components/schemas/users/user.yaml (path from content root)

components:
  schemas:
    User:
      # The type was specified in the separated schema file,
      # but it is not read during the initial rendering in Swagger UI 
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string

Describe the bug you're encountering

I'm developing an API server based on Spring Boot and providing OAS 3.1 with Springdoc. Instead of using annotations, I configured OAS 3.1 in YAML format. I successfully modularized the schema specifications by separating them into different files and using the $ref property.

However, as shown in the screenshot below, the initial type rendered in the Schema tab of Swagger UI appears as any. At first, I thought it might be because Any is the top-level type in Kotlin, but when toggling the schema, the any type changes to object. I suspect that before finding the file via the $ref property, the modularized schema is not read, resulting in the initial type being any.

When I first modularized, my intention was to set only the $ref property in the OAS file. However, due to the issue mentioned above, I'm temporarily setting the type property as well. I'm registering this issue to see if there is a nicer solution.

To reproduce...

Steps to reproduce the behavior:

1. Run the Spring Boot application.
2. Navigate to the default path {origin}:{port}/swagger-ui/index.html.
3. Scroll down to the Schemas tab.
4. Verify that the type in the schema defined with OAS 3.1 is set to any.
5. Select 'Expand all'.
6. Confirm that the type has changed to object, then select 'Collapse all' again.
7. From this point on, the type will continue to be displayed as object.

Expected behavior

The expected result is that the specified schema type should be rendered as object, but the actual result is that it is rendered as any.

Screenshots

Initial Swagger UI rendering	When selecting Expand All	When selecting Collapse again

Additional context or thoughts

I initially registered this issue with springdoc-openapi. I was advised to seek feedback here since the issue appears to occur during UI rendering.

I confirmed that the issue persists with the following dependencies as well:

• Kotlin 1.9 / Spring Boot 3.3.3
• org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0 (Swagger UI 5.17.14)

I also found a temporary solution as shown below, but I'm not sure if I should continue using it this way.

resources/static/openapis/users.yaml (path from content root)

openapi: 3.1.0

# (...)

components:
  schemas:
    User:
      # Instead of specifying the type in the separated file,
      # it works if the type is specified at the same location as the $ref property.
      type: object
      $ref: 'components/schemas/users/user.yaml#/components/schemas/User'

[ekasnh]

Hey I can contribute in this issue can you give a little more context about this

[corock]

@ekasnh Hi. I thought I had provided enough context in the description, but what additional information do you need?
Please let me know and I'll respond.