Как определить пример даты в MicroProfile OpenAPI - PullRequest
Новая
       87

Как определить пример даты в MicroProfile OpenAPI

0 голосов
/ 27 ноября 2018

Я попытался создать минимальный пример проблемы.

Допустим, у нас есть простой возвращаемый объект: 

public class Result {

    @Schema(example = "2012-01-01")
    private LocalDate sampleDate;

    // omitted getter and setter
}

, возвращаемый простой конечной точкой JAX-RS: 

@Path("/example")
@Produces(MediaType.APPLICATION_JSON)
public class Resource {

    public List<Result> example() {
        // omitted implementation
    }

}

MicroProfile OpenAPI в Open Liberty автоматически генерирует следующий файл OpenAPI (Swagger): 

openapi: 3.0.0
info:
  title: Deployed APIs
  version: 1.0.0
servers:
- url: http://localhost:9080/api
paths:
  /example:
    get:
      operationId: example
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Result'
components:
  schemas:
    Result:
      type: object
      properties:
        sampleDate:
          type: string
          format: date
          example: 2012-01-01

Проблема заключается в том, что встроенный интерфейс Swagger отображает пример даты в виде пустого объекта JS:

Swagger UI screenshot

Я не уверен, является ли это ошибкой на стороне пользовательского интерфейса Swagger, потому что, если я не предоставлю никакого примера в аннотации Java = любой пример в файле OpenAPI, он будет отображатьНапример, текущий день, например: 

[
  {
    "sampleDate": "2018-11-27"
  }
]

Все работает правильно, когда я вручную редактирую вывод OpenAPI.И одинарные, и двойные кавычки решают проблему: 

...
sampleDate:
  type: string
  format: date
  example: '2012-01-01'

или 

...
sampleDate:
  type: string
  format: date
  example: "2012-01-01"

будет давать ожидаемый результат: 

[
  {
    "sampleDate": "2012-01-01"
  }
]

Вопрос в том, как изменить аннотации наполучить желаемый выход OpenAPI.Одиночные кавычки автоматически экранируются: 

@Schema(example = "'2012-01-01'")
private LocalDate sampleDate;

будет выдавать: 

...
sampleDate:
  type: string
  format: date
  example: '''2012-01-01'''

Дополнительные двойные кавычки в Java не влияют на результат: 

@Schema(example = "\"2012-01-01\"")
private LocalDate sampleDate;

выдаст тот же вывод без кавычек: 

...
sampleDate:
  type: string
  format: date
  example: 2012-01-01

Я знаю, что могу написать вывод yaml OpenAPI вручную, но это мое последнее средство, потому что я не хочу жертвовать автоматической генерацией только потому, что примеры дат не ведут себя какЯ хочу.Может быть, некоторые OASFilter могут быть реализованы для автоматического переноса значений в примере даты, или я просто упускаю что-то очевидное здесь.

1 Ответ

0 голосов
/ 27 ноября 2018

Я подтвердил поведение, которое вы описываете.В случае проблемы с Swagger-UI, который поставляется с Microprofile OpenAPI, вы можете открыть вопрос здесь: Swagger UI GitHub .

Полученное значение без кавычек является полностью допустимым yaml, поэтому пользовательский интерфейс долженбыть в состоянии разобрать это как есть.

...