3

这与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;
}

PortBinding执行

@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，它必须与地图中实际对象的结构保持同步：

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

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

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

4

1 回答 1

-1

我对这个话题做了一些研究，也没有得出令人满意的结论。该@Schema.pattern领域的文档（此处）指出：

当与特定媒体类型相关联时，示例字符串应由消费者解析以将其视为对象或数组。

所以我认为你的“黑客”是唯一的出路..

于 2021-07-09T10:08:30.853 回答