Swagger Best practices

Question

В настоящее время я определяю Rest API и я намерен использовать Swagger для его документирования. Я уже начал определять свои спецификации API с помощью Open Api Спецификация в YAML в Редактор Swagger.

Тогда я понимаю, что я представлю этот файл в Форс-Codegen генерировать реализацию сервера, а также к Swagger-UI (чьи статика файлы будут предварительно наклеить на мой сервер), чтобы выставить интерактивная документация.

Согласно Swagger, это сверху вниз.

Но позже мне, вероятно, понадобится изменить этот API, и я хочу сделать это через этот утомительно YAML-файл, ранее определенный, чтобы API был легко модифицирован кем-либо (и Language-agnostic).

1. ли способ сделать это, чтобы изменить файл определения, а затем повторно использовать Форс-Codegen? Под этим подходом я предполагаю, что я не могу даже слегка изменить API непосредственно в коде сервера реализации, не рискуя иметь устаревшую документацию.

И если я решил сделать Восходящего подход (через Swagger-ядра аннотаций), я буду сдерживать все мои дальнейшие изменения происходят в серверном коде реализации, и мой файл первоначального определения будет никогда не будет использоваться снова.

2. Таким образом, возникает еще один вопрос: существует ли общий способ обращения с Swagger, когда мы хотим изменить API как через файл спецификации, так и через код сервера реализации (я полагаю, что файл, который Swagger-core может генерировать меня из моего кода, никогда не будет похож на мою начальную, которую я определил вручную).

Спасибо за ваши проблемы.

Answer 1

Чтобы поддерживать документацию по API, лучший способ действий, который я могу предложить, - следовать гибридному подходу.

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

Затем, когда дело доходит до поддержания API-интерфейсов или добавления нескольких новых каждый день (или недели), следуйте за ним снизу вверх. У вас уже есть предыдущий код, единственное, что вам нужно сделать, это добавить еще несколько аннотаций или определений API.

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

Answer 2

Мое мнение может быть предвзятым.

Для API-клиентов в большинстве случаев не требуется настраивать его.Если вы обнаружите, что вам необходимо настроить его в соответствии с вашими требованиями, может возникнуть необходимость начать обсуждение через https://github.com/swagger-api/swagger-codegen/issues/new (а также, пожалуйста, проверьте, какие параметры доступны для настройки вывода, например, для PHP, запустите java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php)

Для сервера stub, в идеале разработчикам нужно только сосредоточиться на логике бизнеса/приложения и восстановить серверную заглушку при добавлении/удалении/обновлении конечных точек (но я не думаю, что все серверные заглушки могут это достичь)

Отказ от ответственности: I 'm главный вкладчик в Swagger Codegen