openapi-процессор – это небольшой фреймворк для обработки файлов yaml с открытым API. В настоящее время open api-процессор обеспечивает генерацию кода java для Spring Boot и преобразование в json.
Он поддерживает gradle и maven для запуска любого открытого api-процессора в рамках процесса сборки.
См. документацию для получения дополнительной информации. Существует также игровая площадка для предварительного просмотра процессоров.
openapi-processor-spring (aop-spring) генерирует Java-код на стороне сервера для загрузки Spring из описания открытого API. Он генерирует интерфейсы для конечных точек со всеми необходимыми аннотациями Spring и генерирует классы моделей (простые POJO) с аннотациями Джексона для схем OpenAPI, используемых в этих конечных точках.
Создавая контроллер, который реализует сгенерированный интерфейс, становится проще реализовать ожидаемые конечные точки. Spring автоматически подберет все аннотации к сгенерированным методам интерфейса. Вы можете сосредоточиться на реализации.
что такое сопоставление типов?
Генерация кода – дело сложное. Невозможно сгенерировать идеальный код только из описания открытого API. Есть много случаев, когда генератору нужна наша помощь, чтобы сгенерировать код, который нам нравится.
Просто подумайте о коллекциях. Открытый API имеет единую абстракцию схемы для описания коллекций: массив ** |/. Большего ему и не нужно.
Использование массива ((например, Строка[] ) в Java возможно (и это то, что aop-spring использует по умолчанию), но обычно мы предпочитаем более мощную и простую в использовании коллекцию, такую как Список или Установить и т.д.
Вот почему нам нужно сопоставление типов . Сопоставление типов позволяет нам сопоставлять схему открытого API с определенным классом Java.
Генератор использует сопоставление для замены любого вхождения данной схемы открытого API в сгенерированном коде сопоставленным целевым типом Java. Не имеет значения, является ли это параметром, ответом или свойством схемы объекта.
Если схема модели открытого API (которая обычно генерирует класс POJO) сопоставляется с существующим классом Java, aop-spring не будет генерировать (дублирующий) класс POJO.
где указать сопоставления типов?
Сопоставление типов является частью файла конфигурации yaml openapi-процессора mapping.yaml . Он должен быть родным братом файлов yaml Open API (т.Е. находиться в том же каталоге).
Файл выглядит следующим образом:
openapi-processor-mapping: v2 # <1> options: package-name: io.openapiprocessor.mapping # <2> map: # java type mappings # <3>
<1> задает формат файла конфигурации. Он должен присутствовать в версии 2, чтобы использовать формат отображения, описанный ниже.
<2> задает пакет Java для сгенерированных исходных файлов.
<3> карта является родительским ключом всех сопоставлений типов.
как указать сопоставление типов?
Сопоставление типов использует простую нотацию для указания сопоставления:
{collection}: # <1>
{key}: {source type} => {target type} # <2>
<1> это определяет коллекцию сопоставлений. Все сопоставления сгруппированы в пару фиксированных коллекций: типы , параметры , ответы и пути . Коллекция сопоставлений может содержать любое количество сопоставлений.
<2> ключ определяет, какой тип отображения определяется. Например, тип является ключом для глобального сопоставления типов в коллекции типы . Значение ключа сопоставляет тип источника с типом назначения, используя стрелку \=> в качестве оператора сопоставления . { {тип источника} – это имя открытого типа API, а {целевой тип} – полное имя класса Java. Полностью соответствует требованиям, поскольку обработчику требуется имя пакета для создания инструкции импорта для целевого типа.
Давайте взглянем на несколько примеров отображения. Это всего лишь введение и не описывает всех возможностей. Дополнительные сведения см. в документации сопоставление типов .
примеры сопоставления типов
глобальное картографирование
Первое сопоставление – это сопоставление типов global . Помня пример массива выше, мы можем изменить его глобально на java.util. Коллекция :
map:
types: # <1>
- type: array => java.util.Collection # <2>
- type: Foo => io.openapiprocessor.samples.Foo # <3>
<1> типы – это список глобальных сопоставлений типов. Он является глобальным, потому что является прямым потомком карты ключ. < <2> – тип является фактическим элементом сопоставления, и в нем говорится: сопоставьте тип схемы открытого API массива с типом Java java.util. Коллекция
Важно: процессор предполагает, что целевой объект Java массива имеет один универсальный параметр, и он будет автоматически использовать тип свойства массива //элемента в качестве универсального параметра.
<<3> этот отображает схему открытого API Foo к существующему классу Java в нашей кодовой базе.
отображение пути
Второе сопоставление – это сопоставление типов на основе пути , и оно весьма полезно. Это позволяет нам ограничить правило сопоставления одной конечной точкой. Он не используется ни для какой другой конечной точки.
Продолжайте читать здесь .
Первоначально опубликовано на Первоначально опубликовано на 14 августа 2020 года.
Оригинал: “https://dev.to/hauner/openapi-processor-spring-type-mapping-4ecj”