Описываешь ли контроллеры с помощью Swagger-аннотаций

Использование Swagger-аннотаций для документирования REST API

Да, я регулярно использую Swagger-аннотации (OpenAPI) для документирования REST контроллеров. Это стандартная практика в современной Java разработке, которая обеспечивает автоматическую генерацию API документации и интерактивного UI для тестирования.

Основные аннотации Swagger/OpenAPI

1. @Operation — документирование операции (endpoint)

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "User Management", description = "Endpoints for managing users")
public class UserController {
    
    @GetMapping("/{id}")
    @Operation(
        summary = "Get user by ID",
        description = "Retrieve user information by unique identifier"
    )
    public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) {
        // ...
    }
}

2. @Parameter — документирование параметров

@GetMapping("/{id}")
@Operation(summary = "Get user by ID")
public ResponseEntity<UserDTO> getUserById(
    @PathVariable
    @Parameter(
        name = "id",
        description = "Unique user identifier",
        example = "123"
    )
    Long id
) {
    return ResponseEntity.ok(userService.findById(id));
}

@GetMapping("/search")
@Operation(summary = "Search users")
public ResponseEntity<List<UserDTO>> searchUsers(
    @RequestParam
    @Parameter(
        description = "Search query",
        example = "John"
    )
    String query,
    
    @RequestParam(defaultValue = "0")
    @Parameter(
        description = "Page number",
        example = "0"
    )
    int page
) {
    return ResponseEntity.ok(userService.search(query, page));
}

3. @RequestBody с Schema аннотациями

@PostMapping
@Operation(
    summary = "Create new user",
    description = "Create a new user with provided details"
)
public ResponseEntity<UserDTO> createUser(
    @RequestBody
    @io.swagger.v3.oas.annotations.media.Content(
        mediaType = "application/json",
        schema = @io.swagger.v3.oas.annotations.media.Schema(
            type = "object",
            example = "{\"name\": \"John\", \"email\": \"john@example.com\"}"
        )
    )
    CreateUserRequest request
) {
    return ResponseEntity.status(201).body(userService.create(request));
}

4. @ApiResponse — документирование ответов

@GetMapping("/{id}")
@Operation(summary = "Get user by ID")
@ApiResponse(
    responseCode = "200",
    description = "User found",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = UserDTO.class)
    )
)
@ApiResponse(
    responseCode = "404",
    description = "User not found",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = ErrorResponse.class)
    )
)
@ApiResponse(
    responseCode = "500",
    description = "Internal server error"
)
public ResponseEntity<UserDTO> getUserById(
    @PathVariable Long id
) {
    return userService.findById(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());
}

Полный пример REST контроллера с Swagger

@RestController
@RequestMapping("/api/v1/users")
@Tag(
    name = "User Management",
    description = "APIs for managing user accounts and profiles"
)
public class UserController {
    
    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }
    
    @GetMapping("/{id}")
    @Operation(
        summary = "Get user by ID",
        description = "Retrieve detailed user information",
        tags = {"User Management"}
    )
    @ApiResponse(
        responseCode = "200",
        description = "User retrieved successfully",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = UserDTO.class)
        )
    )
    @ApiResponse(
        responseCode = "404",
        description = "User not found"
    )
    public ResponseEntity<UserDTO> getUserById(
        @PathVariable
        @Parameter(description = "User ID", example = "1")
        Long id
    ) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElseThrow(() -> new UserNotFoundException(id));
    }
    
    @PostMapping
    @Operation(
        summary = "Create new user",
        description = "Register a new user account"
    )
    @ApiResponse(
        responseCode = "201",
        description = "User created successfully",
        content = @Content(
            schema = @Schema(implementation = UserDTO.class)
        )
    )
    @ApiResponse(
        responseCode = "400",
        description = "Invalid user data"
    )
    public ResponseEntity<UserDTO> createUser(
        @RequestBody
        @Valid
        CreateUserRequest request
    ) {
        UserDTO created = userService.create(request);
        return ResponseEntity
            .status(HttpStatus.CREATED)
            .body(created);
    }
    
    @PutMapping("/{id}")
    @Operation(summary = "Update user")
    public ResponseEntity<UserDTO> updateUser(
        @PathVariable Long id,
        @RequestBody @Valid UpdateUserRequest request
    ) {
        UserDTO updated = userService.update(id, request);
        return ResponseEntity.ok(updated);
    }
    
    @DeleteMapping("/{id}")
    @Operation(summary = "Delete user")
    @ApiResponse(responseCode = "204", description = "User deleted")
    public ResponseEntity<Void> deleteUser(
        @PathVariable Long id
    ) {
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

DTO класс с Swagger аннотациями

@Data
@AllArgsConstructor
@NoArgsConstructor
@Schema(description = "User Data Transfer Object")
public class UserDTO {
    
    @Schema(
        description = "Unique user identifier",
        example = "1"
    )
    private Long id;
    
    @Schema(
        description = "User full name",
        example = "John Doe",
        minLength = 1,
        maxLength = 255
    )
    private String name;
    
    @Schema(
        description = "User email address",
        example = "john@example.com"
    )
    @Email
    private String email;
    
    @Schema(
        description = "User creation timestamp",
        example = "2024-01-15T10:30:00Z"
    )
    private LocalDateTime createdAt;
}

Конфигурация SpringDoc OpenAPI

@Configuration
public class OpenApiConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("User Management API")
                .version("1.0.0")
                .description("REST API for user management")
                .contact(new Contact()
                    .name("API Support")
                    .email("support@example.com")))
            .servers(List.of(
                new Server()
                    .url("http://localhost:8080")
                    .description("Development"),
                new Server()
                    .url("https://api.example.com")
                    .description("Production")
            ));
    }
}

Преимущества использования Swagger

• Автоматическая документация: не нужно поддерживать документацию вручную
• Интерактивный UI (Swagger UI): доступен по /swagger-ui.html
• Тестирование API: можно тестировать endpoint'ы прямо из браузера
• OpenAPI стандарт: совместимость с инструментами и генераторами кода
• Контроль версий: документация всегда синхронна с кодом
• Контракты для фронтенда: четкое определение запросов и ответов

Maven зависимости

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

Заключение

Связь Swagger-аннотаций — это не просто рекомендация, а лучшая практика в REST API разработке. Она экономит время, предотвращает ошибки и улучшает сотрудничество между фронтенд и бэкенд командами. Каждый профессиональный REST сервис должен быть полностью задокументирован через Swagger/OpenAPI.