Skip to content

[Bug]: x-nullable lost for shared $ref responses during Swagger 2.0 to OAS3 conversion #2269

@esaezgil

Description

@esaezgil

Description

When converting Swagger 2.0 specifications to OpenAPI 3.0, the x-nullable vendor extension is lost for the second and subsequent endpoints when multiple endpoints share the same response definition via $ref.

The parser returns a valid OpenAPI 3.0 object, but the nullable field (converted from x-nullable: true) is missing in all but the first endpoint that reference the shared response.

Affected Version

2.1.37 (and likely previous versions)

Steps to Reproduce

Create a sample spec that shares a response across endpoints with a property set to x-nullable. Parse and convert with resolveFully enabled:

import io.swagger.parser.OpenAPIParser;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.parser.core.models.ParseOptions;
import io.swagger.v3.parser.core.models.SwaggerParseResult;

public class TestMissingNullableForSharedResponse {
    public static void main(String[] args) {
        String spec = """
            swagger: '2.0'
            info:
              version: 1.0.0
              title: Test
            responses:
              SharedResponse:
                description: Shared response
                schema:
                  type: object
                  properties:
                    optional_field:
                      type: integer
                      x-nullable: true
            paths:
              /endpoint1:
                get:
                  responses:
                    '200':
                      $ref: '#/responses/SharedResponse'
              /endpoint2:
                get:
                  responses:
                    '200':
                      $ref: '#/responses/SharedResponse'
            """;

        ParseOptions options = new ParseOptions();
        options.setResolve(true);
        options.setResolveFully(true);

        SwaggerParseResult result = new OpenAPIParser().readContents(spec, null, options);
        OpenAPI api = result.getOpenAPI();

        Schema endpoint_1 = getOptionalField(api, "/endpoint1");
        System.out.println("/endpoint1 nullable: " + endpoint_1.getNullable());

        Schema endpoint_2 = getOptionalField(api, "/endpoint2");
        System.out.println("/endpoint2 nullable: " + endpoint_2.getNullable());
    }

    private static Schema getOptionalField(OpenAPI api, String path) {
        return (Schema) api.getPaths().get(path)
                .getGet()
                .getResponses().get("200")
                .getContent().values().iterator().next()
                .getSchema()
                .getProperties().get("optional_field");
    }
}

Expected Behavior

Both endpoints should have nullable: true on the optional_field property after conversion

Actual Behavior

Only the first endpoint has nullable: true. Subsequent endpoints have nullable: null

Logs / Stack Traces

No exceptions thrown. The conversion completes successfully but produces incorrect output.

Environment

  • Java version: OpenJDK 25
  • Build tool: Maven 3.6.3
  • OS: Linux (Ubuntu)

Additional Context

Checklist

  • I have searched the existing issues and this is not a duplicate.
  • I have provided sufficient information for maintainers to reproduce the issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions