java - Swagger 2 注释 - map 的有意义的模式示例

Question

这与 this other question for Swagger 1 几乎相同，除了它与 Swagger 2 相关。

简而言之，我有一个正在尝试注释的实现，以便生成 OpenApi 3 规范。其中一个模型有一个 map 属性，我想为它生成一个很好的有意义的样本。

例如，查看 containerCreate Docker API ，在HostConfig下，有一个PortBindings对象，它有一个条目"22/tcp":

{
    "HostConfig": {
        "PortBindings": {
          "22/tcp": [    <== niceeee
            {
              "HostPort": "11022"
            }
          ]
        }
    }
}

不幸的是，从我的来源生成的文档有些相似但用处不大。虽然 PortBinding 示例是正确且有用的，但 "additionalProp1" 并没有真正的意义:

{
    "HostConfig": {
        "PortBindings": {
          "additionalProp1": [    <== not so nice
            {
              "HostIp": "127.0.0.1",
              "HostPort": "8080"
            }
          ]
        }
    }
}

HostConfig实现

@Schema(description = "Container configuration that depends on the host we are running on")
public class HostConfig implements Serializable {
    @Schema(description = "A map of exposed container ports and the host port they should map to.")
    @Nullable
    @JsonProperty("PortBindings")
    private Map<String, List<PortBinding>> portBindings;
}

端口绑定(bind)实现

@Schema(description = "Host IP and port to which to bind a container port")
public class PortBindingDefinition implements Serializable {
    @Schema(description = "The host IP address", nullable = true, example = "127.0.0.1")
    @Nullable
    @JsonProperty("HostIp")
    private String hostIp;

    @Schema(description = "The host port number, as a string", example = "8080")
    @NotEmpty
    @JsonProperty("HostPort")
    private String hostPort;
}

---

我可以在其中粘贴一个 json 作为示例，但这似乎更像是 hack，它必须与 map 中实际对象的结构保持同步:

@Schema(description = "A map of exposed container ports and the host port they should map to.",
        example = "{\"PortBindings\": {\"22/tcp\": [{\"HostPort\": \"11022\"}]}}")

除此之外，我不知道如何实现相同的目标，以及 Swagger examples到目前为止没有太大帮助。

---

最重要的是，有什么优雅的方法可以实现这一目标吗？

Answer 1

我对这个话题做了一些研究，也没有得出令人满意的结论。@Schema.pattern 字段 ( here ) 的文档指出:

When associated with a specific media type, the example string shallbe parsed by the consumer to be treated as an object or an array.

所以我认为您的“hack”是唯一的出路..