Java / Spring: как создать весь документально оформленный Swagger CRUD REST API с ускорением

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

В нашей предыдущей статье мы рассмотрели тему автоматической генерации REST API. Точнее, мы продемонстрировали, как сгенерировать полностью CRUD REST API для вашей базы данных, используя обновленный плагин Spring Integration от Speedment.

Сегодня мы продвинемся в этом знании и продемонстрируем, как одним щелчком создать интерактивную документацию для вашего REST API.

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

Вам нравятся потоки Java?

Если ответом на этот вопрос является «Да!», «Абсолютно!» или, может быть, «Черт, да!», тогда Speedment — правильный инструмент для вас. Speedment — это инструментарий и среда исполнения Java ORM, использующие чистые потоки Java в качестве интерфейса между вашим приложением и базой данных.

Наряду с уже знакомым API-интерфейсом Streams Speedment предоставляет конечным пользователям графический инструмент для создания представления Java вашей базы данных за считанные секунды, что позволяет им полностью оставаться в среде только для Java.

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

Прежде чем мы начнем

Для создания документации по API REST Speedment использует комбинацию спецификации OpenAPI и пользовательского интерфейса Swagger.

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

Если вы следовали руководству в нашей предыдущей статье , где мы объясняем, как сгенерировать REST API с помощью Speedment, вам нужно всего лишь добавить пару зависимостей в файл pom.xml вашего проекта:

С другой стороны, если вы начинаете с нуля, перейдите к Initializer, где вы сможете сгенерировать проект Speedment с поддержкой Spring. Как только вы дойдете до инициализатора, вам будет предоставлено множество опций для настройки вашего проекта. Одним из параметров конфигурации, который особенно важен, является раздел «Плагины» инициализатора.

Чтобы включить поддержку Spring в вашем новом проекте Speedment, установите флажок рядом с опцией «Spring». Когда вы будете довольны конфигурацией вашего проекта, нажмите кнопку «Загрузить» в нижней части инициализатора.

Когда вы будете готовы, вы можете запустить Speedment Tool, выполнив следующую команду из корневой папки шаблона вашего проекта:

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

Если вы впервые используете Speedment, возможно, вы захотите ознакомиться с рабочим процессом, следуя краткому руководству « Hello Speedment ».

Сваггер Автоматы

В следующем примере мы будем использовать Sakila, образец базы данных MySQL. Вы можете скачать его как отдельный экземпляр или как контейнер Docker.

Когда вы откроете Speedment Tool и успешно подключитесь к своей базе данных, вам будет представлен пользовательский интерфейс, содержащий метаданные о вашей базе данных и некоторые параметры, которые вы можете настроить:

Если вы нажмете кнопку «Создать» в верхнем баннере, будет создано представление вашей базы данных на Java. Чтобы сгенерировать документацию для вашего REST API, вы должны включить опцию «Сгенерировать REST-документацию», которая находится в представлении проекта (доступ к которому осуществляется путем выбора верхнего узла в дереве).

После включения станут доступны дополнительные параметры конфигурации, что позволит вам дополнительно настроить сгенерированную документацию:

В следующий раз, когда вы обновите свой проект Spring, будут сгенерированы некоторые специфические конфигурации OpenAPI. Для просмотра и использования сгенерированной документации вам необходимо запустить приложение Spring. Для этого выполните следующую команду:

Как только ваше приложение Spring будет запущено и запущено, вы можете найти сгенерированную документацию Swagger на следующей конечной точке http: // localhost: 8080 / swagger-ui.html

В зависимости от того, как вы настроили свой проект, вы можете увидеть разные результаты в сгенерированной документации. Например, если вы отключите генерацию REST API для определенной таблицы, при следующей регенерации проекта конечная точка для этой таблицы будет недоступна в документации.

Сгенерированная документация Swagger позволяет вам мгновенно узнать, какие конечные точки REST зарегистрированы вашим приложением, какие методы HTTP доступны для каждой конечной точки, и выполнять HTTP-запросы для этих конечных точек непосредственно из пользовательского интерфейса Swagger:

Если вы не уверены, что требуется в теле запроса, вы можете найти модели тела запроса в нижней части документации, в разделе «Модели»:

Примечание. При подключении к конечной точке Swagger, если вы получаете следующее приглашение, убедитесь, что ваша точка входа Spring находится в правильном пакете (должен быть выше или в том же пакете, в котором находится конфигурация Swagger):

Обычно это признак того, что ваша конфигурация Swagger не была отсканирована Spring.

Резюме

Написание хорошей и понятной документации может быть долгим и утомительным процессом. Благодаря обновлению плагина Speed ​​Boot Spring Boot пользователи могут создавать интерактивную документацию для своего REST API за считанные секунды.

Ресурсы

Статья «Как сгенерировать API-интерфейс CRUD REST для всей базы данных с ускорением»

Speedment Initializer, способный генерировать шаблоны проектов

Ускорение на GitHub

Авторы

Пер Минборг
Мислав Миличевич