Преобразуйте классы документов MongoDB в JSON!

Введите классы документов MongoDB, чтобы получить пример JSON! Поддержка: Spring Data MongoDB @Document. Удобно для документации API и тестовых тел запросов (mock request body).
Spring Data MongoDB
Результат
 

Преобразуйте классы документов MongoDB в JSON!

Подайте класс @Document из Spring Data MongoDB вместе с его встроенными классами и records — и он построит пример JSON того, что возвращает контроллер, отдавая этот документ. Форма следует стандартной сериализации Jackson в Spring Boot, так что описывает ответ API, а не BSON, хранящийся в MongoDB.

Экономит время на документах MongoDB, полных встроенных списков, полей Map и меток времени Instant, где писать пример ответа вручную утомительно, и делает видимым разрыв между форматом хранения и форматом ответа.

Как пользоваться

  1. Вставьте класс @Document и его встроенные классы или records в поле Spring Data MongoDB.
  2. Корнем вывода становится класс документа, на который не ссылается ни один другой класс.
  3. Прежде чем использовать JSON в документации или тестах, замените заглушки id и дат реалистичными значениями.

Пример

Вход (Java · Spring Data MongoDB)
@Document(collection = "devices")
public class Device {
    @Id
    private String id;
    private String serial;
    @Field("fw")
    private String firmwareVersion;
    private Map<String, Double> lastReadings;
    private List<Alert> alerts;
    private Instant registeredAt;
}

record Alert(String level, String message, Instant raisedAt) {}
Результат (JSON)
{
  "id": "",
  "serial": "",
  "firmwareVersion": "",
  "lastReadings": {
    "key": 0
  },
  "alerts": [
    {
      "level": "",
      "message": "",
      "raisedAt": "1970-01-01T00:00:00Z"
    }
  ],
  "registeredAt": "1970-01-01T00:00:00Z"
}

Alert в List<Alert> — это record, поэтому его компоненты level, message и raisedAt становятся полями. Map<String, Double> превращается в {"key": 0}, а Instant — в UTC-строку с Z на конце. @Field("fw") переименовывает только хранимое поле в MongoDB, поэтому ключ JSON остаётся firmwareVersion.

Возможности

  • Компоненты Java record, как в record Alert(String level, ...), читаются как поля.
  • List и Set становятся массивами из одного элемента; Map<String, T> — {"key": value}.
  • Instant, ZonedDateTime и OffsetDateTime дают 1970-01-01T00:00:00Z, а LocalDateTime — строку без смещения.
  • Поля типа ObjectId получают строку-пример ObjectId в hex.
  • Классы, связанные через @DBRef, становятся вложенными объектами, если они есть во вводе.
  • @JsonIgnore, @JsonProperty, @JsonIgnoreProperties и унаследованные поля подчиняются тем же правилам, что и на JPA-странице.

Сценарии использования

Ответы со множеством встроенных документов

Структуры, которые MongoDB упаковывает в один документ, — списки отзывов, карты опций, массивы истории — дают длинные примеры ответов. Вставьте классы, и каждый вложенный уровень будет расписан за вас.

Сравнение формы хранения и формы ответа

Короткие имена через @Field или поля, отображённые на _id, делают ключи в базе отличными от ключей API. Вывод показывает сторону API, так что их можно положить рядом.

Примечания и ограничения

  • Аннотации маппинга, такие как @Field("..."), @Indexed и @TextIndexed, не меняют ключи JSON и не отражаются.
  • @Id String id хранится как _id, но из Jackson выходит как id — это и показывает вывод.
  • Стандартный Jackson в Spring Boot пишет org.bson.types.ObjectId как объект с timestamp и date, а не как hex-строку. Чтобы отдавать строковую форму, показанную здесь, зарегистрируйте ToStringSerializer или используйте id типа String.
  • Классы, отсутствующие во вводе, включая типы Spring Data вроде GeoJsonPoint, становятся null.

Частые вопросы

Каким должен быть мой @Id — ObjectId или String?

С String Spring Data преобразует его в ObjectId при сохранении, а API возвращает чистую hex-строку. Если оставить тип ObjectId, для ответов потребуется дополнительная настройка Jackson.

Действительно ли поля @DBRef возвращаются вложенными объектами?

@DBRef разрешает ссылочный документ при чтении (при первом обращении, если он ленивый), так что ответы содержат вложенный объект. Ручные ссылки, хранящие только id типа ObjectId или String, возвращают лишь id.

Как выглядит свободное поле Map<String, Object>?

Тип его значений неизвестен, поэтому оно становится {"key": null}. Прежде чем помещать его в документацию, замените на значения того вида, который вы реально храните.