Аннотации Swagger 2 — пример осмысленной схемы для карт

Это почти то же самое, что другой вопрос для Swagger 1, за исключением того, что это связано с Swagger 2.

Короче говоря, у меня есть реализация, которую я пытаюсь аннотировать, чтобы создать спецификацию OpenApi 3. У одной из моделей есть свойство карты, и я хочу создать для нее хороший осмысленный образец.

Например, просмотрев 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 в качестве примера, но это больше похоже на хак, и его нужно синхронизировать со структурой реальных объектов на карте:

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

Кроме этого, я не могу понять, как добиться того же, и Примеры Swagger пока не очень помогли.


В итоге, есть ли какой-нибудь элегантный способ добиться этого?


person Morfic    schedule 11.10.2018    source источник
comment
Есть обновления по этому вопросу?   -  person krismath    schedule 23.09.2019


Ответы (1)


Я провел некоторое исследование по этой теме и тоже не пришел к удовлетворительному выводу. Документация по полю @Schema.pattern (здесь) гласит:

Когда строка примера связана с конкретным типом носителя, она должна анализироваться потребителем для обработки как объекта или массива.

Поэтому я предполагаю, что ваш взлом - единственный путь.

person Mario Hammer    schedule 09.07.2021