如何使用springdoc-openapi使所有可选的OpenAPI参数为空？

zaq34kh6 于 2023-05-27 发布在 Spring

关注(0)|答案(2)|浏览(573)

springdoc-openapi库会根据生成的OpenAPI文档中的要求自动标记某些属性。例如，注解为@NotNull的属性将包含在生成的YAML文件的必需属性列表中。
该库没有做的一件事是将可选属性标记为nullable: true。但是，默认情况下，Sping Boot 应用程序将在请求中接受null，并在可选属性的响应中返回null。这意味着OpenAPI文档和端点的行为之间存在差异。
手动将任何单个属性标记为可空是很简单的：只需将@Schema(nullable = true)添加到字段或访问器。但是，在具有多个属性的大型模型中，我更希望以与required属性相同的方式自动确定该属性。也就是说，如果属性不是必需的，我希望它是nullable，反之亦然。
如何在springdoc-openapi生成的OpenAPI文档中获取标记为nullable: true的可选属性？

示例

import io.swagger.v3.oas.annotations.media.Schema;
import javax.validation.constraints.NotNull;

public class RequiredExample {
    @NotNull
    private String key;

    private String value;

    public String getKey() { return key; }
    public void setKey(String key) { this.key = key; }
    public String getValue() { return value; }
    public void setValue(String value) { this.value = value; }
}

生成的OpenAPI文档：

"components": {
  "schemas": {
    "RequiredExample": {
      "required": [
        "key"
      ],
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    }
  }
}

需要的OpenAPI文档：

"components": {
  "schemas": {
    "RequiredExample": {
      "required": [
        "key"
      ],
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "value": {
          "type": "string"
          "nullable": true
        }
      }
    }
  }
}

spring

来源：https://stackoverflow.com/questions/69310598/how-can-i-make-all-optional-openapi-parameters-nullable-using-springdoc-openapi

2条答案

按热度按时间

unftdfkk1#

您可以直接使用@Schema注解属性。这里的关键是nullable和requiredMode都必须下注。

import io.swagger.v3.oas.annotations.media.Schema;
import javax.validation.constraints.NotNull;

public class RequiredExample {
    @NotNull
    private String key;

    @Schema(nullable = true, requiredMode = Schema.RequiredMode.REQUIRED)
    private String value;

    public String getKey() { return key; }
    public void setKey(String key) { this.key = key; }
    public String getValue() { return value; }
    public void setValue(String value) { this.value = value; }
}

在某些情况下，this是我的确切用例。

赞(0）回复(0）举报 2023-05-27

64jmpszr2#

一个解决方案是创建一个springdoc-openapi OpenApiCustomiser Spring bean，它将所有属性设置为nullable，除非它们在required属性列表中。这种方法得益于内置的springdoc-openapi对@NotNull和其他类似注解的支持，因为required属性将根据这些属性的存在以标准方式计算。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.stereotype.Component;
import java.util.Map;

@Component
public class NullableIfNotRequiredOpenApiCustomizer implements OpenApiCustomiser {
    @Override
    @SuppressWarnings({"rawtypes", "unchecked"})
    public void customise(OpenAPI openApi) {
        for (Schema schema : openApi.getComponents().getSchemas().values()) {
            if (schema.getProperties() == null) {
                continue;
            }

            ((Map<String, Schema>) schema.getProperties()).forEach((String name, Schema value) -> {
                if (schema.getRequired() == null || !schema.getRequired().contains(name)) {
                    value.setNullable(true);
                }
            });
        }
    }
}

赞(0）回复(0）举报 2023-05-27

我来回答

如何使用springdoc-openapi使所有可选的OpenAPI参数为空？

示例

生成的OpenAPI文档：

需要的OpenAPI文档：

2条答案

相关问题

热门标签

最新问答