Генератор OpenApi ссылается на внешний объект POJO в спецификации файла YAML

Я использую OpenApi v3.3.4 (ранее называвшийся Swagger CodeGen) плагин maven для генерации моего контроллера отдыха с помощью api.yml файлов, в которых я описываю все операции, которые я хочу раскрыть.

В моем случае использования я хочу предоставить метод POST: handleNotification(@RequestBody SignatureNotification notification), тип тела запроса которого создается с помощью другого плагина maven в папке /targer.

На самом деле я определяю SignatureNotification в Componentspart моего файла .yml:

...
requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureNotification'
...

Это генерируется плагином OpenApi, а затем я сопоставляю его с SignatureNotification, который уже существует и имеет те же атрибуты.

Я не очень доволен этим решением, поэтому хочу знать, есть ли способ указать OpenApi Generator использовать внешний объект в качестве ссылки?


openapi-generator swagger-codegen
person Ghassen    schedule 27.11.2019    source источник

Ответы (2)


arrow_upward
4
arrow_downward

Если я правильно понимаю ваши потребности, вы просто хотите, чтобы генератор не создавал снова ваш существующий класс. Если приведенное выше верно, то вы можете настроить плагин importMappings следующим образом:

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>${openapi-generator-maven-plugin.version}</version>
  <configuration>
      ... excluded for simplicity
      <importMappings>
          <importMapping>SignatureNotification=path.to.your.SignatureNotification</importMapping>        
      </importMappings>
  </configuration>
</plugin>

С этой конфигурацией генератор openapi не будет генерировать класс из определения SignatureNotification, вместо этого он будет использовать существующий.

person bilak    schedule 28.11.2019
comment
большое спасибо ! Это хорошо работает, и я просто хочу упомянуть, что в файле .yml нам нужно определить SignatureNotification в области компонентов, имеющей как type: object - person Ghassen; 28.11.2019
comment
@Ghassen. Спасибо за это очень полезное обсуждение. Я пробовал тот же подход, когда отображаю внешний объект из другого пакета. когда я выполняю чистую компиляцию mvn, генератор жалуется на эту ссылку на объект (объект и пакет не являются частью целевой папки генератора), код правильный и сгенерирован, как ожидалось. есть ли способ избежать ошибки компиляции? (доза в упаковке не существует) - person BSL; 02.01.2021

arrow_upward
1
arrow_downward

Теория:

Согласно спецификации openapi, $ref также может быть ссылкой на внешний файл. Вы можете прочитать об этом здесь.

Реальность:

Сказав это, я предпочитаю вообще не использовать его. Спецификация openapi слишком формальна / явна / раздута для работы со ссылками на внешние файлы, imho.

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

Я держу файлы небольшого размера. И как только я хочу обработать их с помощью инструмента, я просто объединяю все вместе. На самом деле написать сценарий для их объединения не так уж и сложно.

структура папок

  • Создаю отдельные файлы в папке components\schemas. Каждый файл содержит одно или несколько определений модели. Я могу поместить их в любую подпапку. (размещение их во вложенных папках не влияет на объединенный файл).

  • А во-вторых, есть папка components\paths, в которой каждый файл может содержать один или несколько путей.

  • Наконец, есть корневой yml-файл, который довольно пуст.

Вот пример сценария для обратного объединения файлов. https://gist.github.com/bvandenbon/b91c0e39387019daaa813fdcaeac2a51

Типичный root.yml файл выглядит так:

openapi: 3.0.1
info:
  title: MyApiServer
  version: "1.0.0"
servers:
  - description: My API server
    url: http://localhost:49361/rs/

Типичный файл модели с зависимостями выглядит так:

зависимости

PS: точечная нотация, которую я использую здесь для имен своих моделей, не обязательна, в именах нет никаких ограничений, кроме тех, которые определены в спецификации openapi. Но исходя из фона java, я предпочитаю называть модели в соответствии с подкаталогом, в котором они находятся. Но ограничения на именование зависят от инструментов генератора документов / кода, которые вы используете. В пользовательском интерфейсе Swagger нет проблем, но инструменты генерации кода имеют некоторые ограничения.

person bvdb    schedule 27.11.2019
comment
Большое спасибо за объяснение, это очень ясно, но моей целью было вызвать внешний класс java, и решение, предложенное @bilak выше, отлично сработало для меня :) - person Ghassen; 28.11.2019