BuildScripts/documentation/JSON Models Generation.md

Описание генератора JSON моделей

Генератор JSON моделей - это скрипт, который автоматически создает классы JSON моделей на основе описания их схемы в файле формата YAML.

Генерируется 2 типа классов:

• классы, описывающие enum;
• классы, описывающие модели.

Классы моделей размечаются для работы с библиотекой LoganSquare и наследуется от абстракного класса ApiModel, содержащего логику валидации.

Классы моделей содержат в себе:

• конструктор без параметров;
• конструктор со всеми возможными параметрами в случае, если модель не наследуется ни от какой другой модели;
• приватные поля, описывающие параметры модели;
• публичный getter и setter для каждого поля модели;
• метод validate для валидации модели;
• метод equals и hashCode на основе всех содержащихся полей;
• метод writeObject и readObject для стандартной сериализации объекта;
• метод copy для создания копии объекта. Создается только в случае, если модель не наследуется ни от какой другой модели.

ВАЖНО! Копирование через метод copy не гарантирует копирование всех объектов, содержащихся во всех полях.

Подключение и использование генератора

Подключаем сабмодуль BuildScripts в папку libraries.

Чтобы подключить скрипт, добавьте в конец файл build.gradle модуля следующую строку:

    apply from: "${rootDir}/libraries/BuildScripts/gradle/jsonModelsGeneration.gradle"

Чтобы зарегистрировать YAML файлы для генерации моделей, в секцию android надо добавить:

android {
      extensions.jsonModelsMapping = ["schemes/api_models.yaml -> ${defaulConfig.applicationId}.logic.api.model",
                                      "schemes/internal_models.yaml -> ${defaulConfig.applicationId}.logic.model"]
    }

• schemes/api_models.yaml - путь к файлу схемы. По умолчанию относительно папки модуля, но можно указать и абсолютный путь;
• -> - разделитель;
• ${applicationId}.logic.api.model - package-name моделей, которые будут сгенерированы на основе этого файла.

Структура файла YAML

YAML файл может содержать 3 типа объектов: описание модели, описание enum, импортированные классы.

Описание модели

Описание начинается с class MyModel:, где MyModel - это имя класса, который будет сгенерирован.

Затем для класса идет описание параметров класса:

• параметр typeArguments: TResponse, TData добавляет к классу указанные аргументы: class MyModel<TResponse, TData>;
• параметр extends: BaseResponse<String> наследует класс от указанного класса: class MyModel extends BaseResponse<String>;
• параметры, описывающие поля класса, например name: string добавляет поле типа String с названием name.

Описание параметра поля класса

В простом виде поле добавляется, как name: string. То есть, указывается имя поля и его тип.

Вообще, поле может быть описано следующими параметрами:

1. Название параметра - это имя поля;
2. jsonName, необязательное - имя параметра в разметке JSON, соответсвующее полю. По умолчанию берется ;
3. type, обязательное - тип поля. Разрешенные типы:
   • строки string, String;
   • целые числа int, Integer, long, Long;
   • дробные числа float, Float, double, Double;
   • буленовские значения boolean, Boolean;
   • дата/время date, datetime, DateTime;
   • списки List<*>;
   • мапы `Map<String, *>;
   • описанные в этом же файле enum'ы;
   • описанные в этом же файле импортированные классы;
4. flags, необязательное - флаги для валидации объекта. Перечисляются через запятую, могут быть:
   • nullable - в поле может прийти null. По умолчанию все поля считаются non-null;
   • missable - JSON может не содержать такого поля. По умолчанию все поля считаются non-missable;
   • solid - если поле содержит коллекцию, то все элементы в ней обязаны быть валидными. По умолчанию не валидные элементы исключаются из коллекции на этапе валидации;
   • non-empty - если поле содержит коллекцию, то она не должна быть пустой. По умолчанию пустые коллекции разрешены.

Пример описания моделей:

class SimpleModel:
  name: string
  age: int
  birthDate: date
  
class ComplexModel:
  id:
    type: long
    jsonName: object_id
  usersList:
    type: List<SimpleModel>
    flags: solid, non-empty
  hasSomeInfo:
    type: boolean
    jsonName: has_info
    flags: nullable

Описание enum'a

Описание начинается с enum MyEnum:, где MyEnum - это имя enum'a, который будет сгенерирован.

Затем идет перечисление всех возможных значений в формате VALUE: json_value, где VALUE - имя значения в enum'e, а json_value - соответствующая этому значению строка в JSON.

Пример:

enum SimpleEnum:
  MALE: male_gender
  FEMALE: female_gender

Описание импортированных классов

Импортированные классы добавляются списком в разделе imports. Все классы должны быть указаны полным именем.

Пример:

imports:
  - android.util.Pair
  - com.myproject.model.UserExtension
  
class MyModel:
  pair: Pair
  users: List<UserExtension>

Импортированные классы нужно использовать в двух случаях:

1. Для них заргеистрированы конвертеры в LoganSquare;
2. Это расширенные или кастомные модели, описанные для LoganSquare вручную.