springdoc-openapi как отобразить массив строк в качестве ответа

Question

В сети нет хороших примеров того, как получить следующий вывод с помощью библиотеки springdocs-openapi (1.5.7). Я хочу получить следующий результат:

      [
  "A", "B", "C"
]

Это код, основанный на предоставленных примерах.

      @Operation(summary = "")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "OK",
                    content = {@Content(mediaType = "application/json",
                            array = @ArraySchema(schema = @Schema(implementation = String.class)),
                            examples = {@ExampleObject("A"), @ExampleObject("B"), @ExampleObject("C")}
                    )})

Это приводит к следующему выводу

      [
  "string"
]

Как вывод, указанный выше ["A", "B", "C"], возможен через библиотеку springdocs-openapi?

Answer 1

Вы неправильно используете. В value Атрибут (также атрибут по умолчанию, если вы ничего не указываете) принимает сериализованный объект JSON из примера полезной нагрузки.

Таким образом, чтобы получить ["A", "B"], вам не нужно несколько, вам нужна одна аннотация для одного примера.

Таким образом, обновление кода, как показано ниже, должно быть полезным.

      @Operation(summary = "Some method")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "OK", content = {
        @Content(
            mediaType = MediaType.APPLICATION_JSON_VALUE,
            array = @ArraySchema(schema = @Schema(implementation = String.class)),
            examples = {
                @ExampleObject("[\"A\", \"B\"]")
            }
        )
    })
})

Ниже показан результат выполнения вышеуказанного кода.

Чтобы указать несколько примеров, должно быть несколько объектов-примеров, как показано ниже.

      @Operation(summary = "Some method")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "OK", content = {
        @Content(
            mediaType = MediaType.APPLICATION_JSON_VALUE,
            array = @ArraySchema(schema = @Schema(implementation = String.class)),
            examples = {
                @ExampleObject(name = "Example 1", summary = "Summary 1", description = "Some desc", value = "[\"A\", \"B\"]"),
                @ExampleObject(name = "Example 2", summary = "Summary 2", description = "Some desc", value = "[\"C\", \"D\"]")
            }
        )
    })
})

ПРИМЕЧАНИЕ . name атрибут @ExampleObject используется для внутренней идентификации примера в файле спецификации.

      "responses": {
  "200": {
    "description": "OK",
    "content": {
      "application/json": {
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "examples": {
          "Example 1": {
            "summary": "Summary 1",
            "description": "Some desc",
            "value": [
              "A",
              "B"
            ]
          },
          "Example 2": {
            "summary": "Summary 2",
            "description": "Some desc",
            "value": [
              "C",
              "D"
            ]
          }
        }
      }
    }
  }
}

И результат такой, как показано ниже