node.js 上招摇的可空字段答案

【问题标题】：nullable fields in swagger on node.jsnode.js 上招摇的可空字段
【发布时间】：2023-03-14 12:33:01
【问题描述】：

我花了很多时间试图找到在 Node.JS 中创建 swagger 文档的解决方案。主库是 swagger-node，您可以在其中创建一个 swagger yaml 文件，然后将控制器添加到其中。它会自动在您的应用中提供 swagger ui 文档，并针对您在 yaml 中指定的模型对请求和响应进行验证。

这很好，但是我有一个要求，我希望某些字段能够显式返回或接受 null 作为值，例如：

{ 
  id: 123,
  description: "string",
  date_sent: null
}

我不想删除date_sent 键，我想明确地将其声明为空。

swagger 规范不支持anyOf，我相信这就是 JSON 模式通常这样做的方式。

我想知道是否有解决方法？也许某些可用于节点的库具有您可以添加的x-nullable 供应商特定标志，或者以某种方式指定我的非必填字段都应该为空。

我是否必须自己编写一些东西来获取我的 swagger 文件，然后在验证器中间件运行之前对其进行修改，还是有人可以建议一些解决方法？

【问题讨论】：

相关：How to define a property that can be string or null in OpenAPI (Swagger)?, How to specify a property can be null or a reference with Swagger?

标签： node.js swagger swagger-ui swagger-editor

【解决方案1】：

nullable 字段在 OpenAPI (fka Swagger) 规范 v3.0.0 中受支持，但在 v2.0 中不支持。可空类型定义如下：

# Can be string or null
type: string
nullable: true

【讨论】：

当我检索数据时，我现在得到的是"fieldName": {"present":true}，而不是实际值。如何将值返回到输出中？
--> 发布了针对这个问题的解决方案：stackoverflow.com/a/59047331/2750563

【解决方案2】：

SwaggerUI 不支持可为空的类型（请参阅 here）。但我使用可为空的属性：

type: ['string','null']

之后此属性从 UI 中消失，但验证仍然有效。

【讨论】：

啊哈！我试过这个，但在 yaml 中我做了 string 和 null 但你必须在 'null' 周围加上引号才能工作。谢谢！另外，如果你添加一个“默认”，那么它会再次出现在示例值中，我猜它只是不知道使用哪个作为示例
哇！非常感谢！我没有考虑默认值。我会在我的项目中尝试一下
顺便说一句，这不是一个有效的 Swagger 类型定义。
正如 Ron 所说，这在 OpenAPI/Swagger 中无效。 Nazar Gargol's answer 是正确的。另见How to define a property that can be string or null in OpenAPI (Swagger)?。
仅供参考，这将使这种类型的属性不会出现在 swagger-codegen 的输出中，这是 Swagger 规范最有用的工具之一。

【解决方案3】：

除了在 type 属性中添加 null 之外，您还可以使用 default 属性。

Swagger.json 属性定义示例：

"due_date": {
  "type": "string",
  "description": "Due date",
  "default": "null"
},

这是一个有效的 Swagger 类型定义，并且仍按预期显示在 Swagger UI 中。

【讨论】：

Swagger 2 的天才答案 - 不知道为什么这没有被投票 - 非常感谢
在进一步的研究中，虽然这似乎工作正常，但遗憾的是它在招摇编辑器中给出了一个错误
这个定义是有效的，因为它使用了字符串"null"，而不是实际的null。这不是 OP 想要的。
顺便说一句，default: null（使用实际的 null 而不是字符串 "null"）在 OpenAPI 2.0 中无效。规范says 的default 值“必须符合定义的类型”——但null 不符合string 类型，而且OpenAPI 2.0 中也没有null 类型。 Nazar Gargol's answer 是这里唯一正确的答案。

【解决方案4】：

只是作为一个提示，因为我偶然发现了这个：当我添加时

type: string
nullable: true`

如答案https://stackoverflow.com/a/42797352/2750563 中所述，我的服务仅返回"fieldName": { "present": true } 而不是实际值！

如果您看到这个，只需将 JsonNullableModule 添加到您的 Jackson 序列化程序中，例如，如果使用 Spring：

@Component
public class JacksonConfiguration {

    @Autowired
    public void configureJackson(ObjectMapper mapper) {
        mapper.registerModule(new JsonNullableModule());
    }

}

然后一切看起来又好了。

【讨论】：