Question

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

简而言之，我正在尝试注释一个实现，以生成OpenApi 3规范。其中一个模型具有map属性，我想为其生成一个不错的有意义的示例。

例如，查看HostConfig下的containerCreate Docker API，有一个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作为示例，但这似乎更像是一种技巧，它必须与地图中实际对象的结构保持同步：

@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) 的文档说明：

<块引用>

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

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

Swagger 2注释-地图的有意义的架构示例

1 个答案: