嵌套类的OpenAPI 3.0 Java注释

问题描述

我正在尝试使组件在使用OpenAPI 3.0 Java批注时看起来嵌套在一起。但是，在另一个对象内引用的每个对象都将被创建为$ ref，而不是被构建为该字段节点。如何在没有$ ref的情况下将其嵌套？

例如：

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

public class ContactInfo{
  String email;
  String phone;
}

为

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

代替

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

解决方法

所有复杂对象都是使用springdoc-openapi生成的，使用$ ref对象进行重用。

默认情况下，此行为来自swagger-core库，用于解析嵌套对象。

这就是说，您可以使用OpenApiCustomiser和swagger类的组合以编程方式定义属性以获得所需的结果：

@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);
    }
}