Генераторы

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

Модификация формата клиентской библиотеки

Не нравится стандартный синтаксис Swagger клиента? Хотите поддержку другого языка? Ничего страшного! Swagger Codegen использует движок jmustache для обработки шаблонов в формате Mustache. Вы можете модифицировать наши шаблоны или создать свои собственные.

Вы можете посмотреть примеры в директории modules/swagger-codegen/src/main/resources/${your-language}. Чтобы создать свои собственные шаблоны, создайте свои собственные файлы и используйте флаг -t, чтобы указать папку с вашими шаблонами. На самом деле это так просто.

Создание своих собственных модулей для генерации кода

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

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar meta \
  -o output/myLibrary -n myClientCodegen -p com.my.company.codegen

Это создаст все необходимые файлы в папке output/myLibrary, включая файл README.md. После модификации и компиляции вы сможете загрузить свою библиотеку с помощью генератора и создать клиенты с собственной логикой.Затем вы компилируете свою библиотеку в папке output/myLibrary командой mvn package и запускаете генератор таким образом:

java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modules/swagger-codegen-cli/target/swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen

Для пользователей Windows вам потребуется использовать ; вместо : в пути к классам, например:

java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar;modules/swagger-codegen-cli/target/swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen

Обратите внимание, что myClientCodegen теперь является опцией, и вы можете использовать обычные аргументы для генерации своей библиотеки:

java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modules/swagger-codegen-cli/target/swagger-codegen-cli.jar \
  io.swagger.codegen.SwaggerCodegen generate -l myClientCodegen \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o myClient

См. также разработка автономного генератора.

Генерация клиента из локальных файлов

Если вы не хотите вызывать свой сервер, вы можете сохранить файлы спецификации OpenAPI в директорию и передать аргумент генератору кода следующим образом:

-i ./modules/swagger-codegen/src/test/resources/2_0/petstore.json

Отлично подходит для создания библиотек на вашем сервере CI, из Swagger Editor... или во время работы над кодом в самолете ✈️.

Игнорирование формата файла

Swagger Codegen поддерживает файл .swagger-codegen-ignore, аналогичный .gitignore или .dockerignore, с которыми вы, вероятно, уже знакомы.Файл игнорирования позволяет лучше контролировать перезапись существующих файлов, чем флаг --skip-overwrite. С помощью файла игнорирования можно указать отдельные файлы или директории, которые следует игнорировать. Это может быть полезно, например, если вам нужна только часть сгенерированного кода.

Примеры:

# Swagger Codegen Ignore
# Строки, начинающиеся с #, являются комментариями

# Это должно совпадать с build.sh, расположенным где угодно.
build.sh

# Соответствует build.sh в корне
/build.sh

# Исключает все рекурсивно
docs/**

# Явно разрешает файлы, исключённые другими правилами
!docs/UserApi.md

# Рекурсивно исключает директории с названием Api
# Вы не можете отменить исключение файлов ниже этой директории.
src/**/Api/

# Когда этот файл находится вложенно под /Api (исключено выше),
# это правило игнорируется, так как родительская директория исключена предыдущим правилом.
!src/**/PetApiTests.cs

# Явно исключает одиночный вложенный файл
src/IO.Swagger.Test/Model/AnimalFarmTests.cs

Файл .swagger-codegen-ignore должен существовать в корне выходной директории.

При первом генерировании кода вы также можете передать опцию CLI --ignore-file-override=/путь/к/файлу_игнорирования для большего контроля над сгенерированным выводом. Обратите внимание, что это полное переопределение, и оно переопределяет файл .swagger-codegen-ignore в выходной директории при повторной генерации кода.Поддержка редактора для файлов .swagger-codegen-ignore доступна в IntelliJ через плагин .ignore.