Оригинал статья https://struchkov.dev/blog/ru/api-swagger/
Swagger — это фреймворк для спецификации RESTful API. Он позволяет не только интерактивно просматривать документацию, но и, например, отправлять запросы с помощью инструмента Swagger UI. Также по спецификации API Swagger можно сгенерировать клиент или сервер.
Как добавить в проект???
Swagger позволяет разработчикам описывать структуру своих API и генерировать интерактивную документацию, клиентские библиотеки и серверные модули для реализации API на разных языках.
Swagger предоставляет спецификацию для документирования REST API, которая называется OpenAPI Specification (OAS). Эта спецификация предоставляет четкий и лаконичный способ описания эндпойнтов, их параметров, моделей запросов и ответов и других аспектов API.
1. Создать проект проект с REST API
Добавить примитивные контроллеры и DTO.
Проверить аннотации! Программа должна запускаться!
2. Настраиваем Swagger
Теперь добавим Swagger в наш проект. Для этого добавьте следующие зависимости в pom.xml:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.2</version>
</dependency>
Для WebFlux используйте другую зависимость:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
<version>2.0.2</version>
</dependency>
Данные зависимости подходят только для проектов на SpringBoot 3. Если вы используете SpringBoot 2, то вам необходимо добавить другие зависимости:
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.2.8</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
3. Важная информация
Swagger автоматически находит список всех контроллеров. При нажатии на любой из них будут перечислены допустимые методы HTTP (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).
Для каждого метода доступные следующие данные: статус ответа, тип содержимого и список параметров.
Поэтому после добавления зависимостей у нас уже есть документация, доступная по ссылке: http://localhost:8080/swagger-ui.
А также есть OAS, доступный по адресу: http://localhost:8080/v3/api-docs.
4. ДОПИСАТЬ ОФОРМЛЕНИЕ
