OpenAPI 3.0 Java Annotations of Nested Class

Question

I am trying to get the components to appear nested together when using OpenAPI 3.0 Java annotations. However, every object that is referenced inside another object are being created as $ref instead of being built out as that field node. How can I get it to nest under without the $ref?

For Example:

public class User{
  int id;
  String name;
  ContactInfo contactInfo;
}

public class ContactInfo{
  String email;
  String phone;
}

as

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        contact_info:
          # The value of this property is an object
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string

instead of

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        contactInfo: {
          $ref: "#/components/schemas/ContactInfo"
        }
    ContactInfo:
      type: object
      properties:
         email:
           type: string
           format: email
         phone:
           type: string

score 1 · Answer 1 · edited Oct 15 '20 at 12:35

All complex objects are generated with springdoc-openapi, using $ref objects for reuse purposes.

This behavior comes by default from the swagger-core library for the resolution of the Nested objects.

This is said, you can define your properties programatically using a combination of OpenApiCustomiser and swagger classes to get your expected result:

@Component
public class MyOpenApiCustomiser extends SpecFilter implements OpenApiCustomiser {
    @Override
    public void customise(OpenAPI openApi) {
        ResolvedSchema resolvedUserSchema = ModelConverters.getInstance()
                .resolveAsResolvedSchema(new AnnotatedType(User.class));
        resolvedUserSchema.schema
                .addProperties("contactInfo", new ObjectSchema()
                        .addProperties("email", new StringSchema().format("email"))
                        .addProperties("phone", new StringSchema()));
        openApi.schema(resolvedUserSchema.schema.getName(), resolvedUserSchema.schema);
        this.removeBrokenReferenceDefinitions(openApi);
    }
}

OpenAPI 3.0 Java Annotations of Nested Class

1 Answers1