Исправление JSON-примера Swagger-Ui - показывать JsonNumber вместо Object - PullRequest
Новая
       7

Исправление JSON-примера Swagger-Ui - показывать JsonNumber вместо Object

1 голос
/ 17 июня 2019

В нашем проекте Java / Spring мы используем Swagger-Ui для автоматического документирования наших REST-API.
В последнее время я попытался обеспечить надлежащую документацию для всех наших API и обнаружил, что для некоторых конечных точек JSON-Structureаргументы методов нечетны.

В проекте у нас есть тип "SerialNo", который в основном представляет собой целое число в определенном диапазоне (10000000 - 39999999).

Внутренне мы используемДжексона для сериализации и десериализации наших объектов (например, для брокера событий), и мы установили, что в JSON-документе SerialNumber выглядит как целое число 

// Product
{
  "header": { // type: ProductHeader
    "serialNo": 17654321
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

, и это также ожидаемая структурас помощью REST-Call.

Теперь Swagger-Ui показывает это в качестве примера: 

// Product
{
  "header": {
    "serialNo": {} // <--- This is missleading
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

Я обнаружил, что могу предоставить пример для параметра, который принимает эту структуруиспользуя @ApiParam(example = "..."), но так как структура стала больше, я не чувствую, что это удовлетворительно, также SerialNo появится в нескольких структурах, и яя думаю, что это утомительно и ошибочно приводить пример для каждого случая в API-документе.

Я добавил @ApiParam в поле в ProductHeader, которое является объектом в "header":

@Getter
@Setter
public class ProductHeader {
   @JsonProperty
   @ApiParam(example = "17654321") private SerialNo serialNo;
   // ...
}

но это ничего не меняет.

Есть ли возможность использовать возможности генерации документации swaggers для получения правильного примера вывода без предоставления примера для полной структуры каждый раз?

...