Использовали ли вы Swagger (OpenAPI) для документирования REST API?

Да, активно использовал Swagger (теперь чаще называемый по имени спецификации — OpenAPI) для автоматической генерации интерактивной документации и клиентских SDK для REST API.

Основные преимущества:

• Автоматизация: Документация генерируется из аннотаций в коде, что минимизирует ручную работу и расхождения.
• Интерактивность: Позволяет тестировать эндпоинты API прямо из браузера через Swagger UI.
• Стандартизация: Спецификация OpenAPI стала отраслевым стандартом для описания API.

Пример настройки в Spring Boot с Springfox (устаревшая, но популярная библиотека):

1. Добавление зависимости (Maven):

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>

2. Конфигурационный класс:

   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
               .paths(PathSelectors.any())
               .build();
       }
   }

3. Аннотирование контроллера:

   @RestController
   @RequestMapping("/api/users")
   @Api(tags = "User Management") // Аннотация Swagger для группировки
   public class UserController {
       @GetMapping("/{id}")
       @ApiOperation(value = "Get a user by ID") // Описание операции
       public ResponseEntity<User> getUser(@PathVariable @ApiParam(value = "User ID", example = "123") Long id) {
           // ... логика метода
       }
   }

После запуска приложения документация будет доступна по адресу http://localhost:8080/swagger-ui/.

Современная альтернатива: Для новых проектов рекомендуется использовать SpringDoc OpenAPI (springdoc-openapi-ui), который лучше интегрирован со Spring Boot и поддерживает OpenAPI 3.