Weird YAML tag in section /components/examples of auto-generated OpenAPI spec file

The issue appears when a combination of tools is used:

• spring-boot-starter-web:2.3.1.RELEASE
• springdoc-openapi-ui:1.4.3
• jackson:2.11.0 (comes with SpringBoot)

Example of auto-generated OpenAPI file with unwanted tag

....
componets:
  ....
  examples:
    umbrellaExample:
      value:
        object: !<Type A>
          type: TYPE_A
          name: x
          description: "y"

!<Type A> doesn’t seem to be a valid YAML tag. Swagger Online Editor tool also complains about this tag and refuses to render such YAML file.

There’s a working example available at https://github.com/EugeneDrm/open-api-tag-bug

Key notes

• there’s an abstract class (AbstractObject) with one or more concrete implementations
• the abstract class (AbstractObject) has a type field
• annotation @JsonTypeInfo is used on the abstract class (AbstractObject) to properly deserialize concrete implementation(s) into abstract reference
• there’s a model class (Umbrella) which references the abstract class (AbstractObject)
• an example object for model class (Umbrella) is defined in OpenAPI components/examples section via OpenAPI bean

Umbrella

public class Umbrella {
  @Schema(description = "This reference to abstract class causes weird YAML tag to be added", anyOf = ConcreteObjectA.class)
  private final AbstractObject object;
  ...
}

AbstractObject

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.EXISTING_PROPERTY,
    property = "type",
    visible = true
)
@JsonSubTypes({
    @JsonSubTypes.Type(value = ConcreteObjectA.class, name = "Type A")
})
public abstract class AbstractObject {
  private final ConcreteType type;
  private final String name;
  ...
}

Controller

@RestController
public class Controller {
  @Operation(summary = "Test Bug", responses = {
      @ApiResponse(responseCode = "200", description = "OK",
          content = @Content(
              schema = @Schema(implementation = Umbrella.class),
              examples = @ExampleObject(ref = "#/components/examples/umbrellaExample", name = "Example with weird YAML tag")
          )
      )
  })
  @GetMapping(value = "/bug", produces = MediaType.APPLICATION_JSON_VALUE)
  public Umbrella bug() {
    return new Umbrella(new ConcreteObjectA("a", "b"));
  }
}

Application

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

  @Bean
  public OpenAPI openApi() {
    return new OpenAPI()
        .components(new Components()
            .addExamples("umbrellaExample", new Example().value(new Umbrella(new ConcreteObjectA("x", "y"))))
        );
  }
}

Expected behavior

• No YAML tag is generated in the examples section

[bnasslahsen]

@EugeneDrm,

Thanks to your clear description, a workaround will be availble on the next release of springdoc-openapi. This fix is already available on the latest snapshot.

[EugeneDrm]

@bnasslahsen thanks, this is very helpful. I was able to run the code snippet and see that the issue is coming from swagger library. I’ll submit a new issue in swagger-core project. Closing this one.