Integrated Swagger OpenAPI docs and add HATEOAS links

Author: irinakomarchenko

README.md

@@ -15,13 +15,32 @@
 - Spring Web (REST API)
 - Spring Data JPA (встроенный Hibernate)
 - PostgreSQL (через Docker Compose)
+- Spring HATEOAS (hypermedia links в API)
+- Swagger/OpenAPI (автоматическая документация)
 - SLF4J + Logback (логирование)
 - JUnit 5 + MockMvc (тестирование контроллеров и API)
 - Maven (сборка и зависимости)
 - Checkstyle (проверка стиля кода)
 - Lombok — (автогенерации геттеров/сеттеров)
 ---
 
+## Описание API и документация
+
+### Swagger OpenAPI
+
+В проект интегрирована автоматическая генерация документации с помощью **Swagger (OpenAPI)**.  
+Документация доступна после запуска приложения:
+
+- **Swagger UI:** [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html)
+- **OpenAPI JSON:** [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs)
+
+### Поддержка HATEOAS
+
+Сервис реализует подход **HATEOAS** (Hypermedia as the Engine of Application State):
+
+- Все ответы API содержат _hypermedia-ссылки_, помогающие навигировать по ресурсам (например, ссылки на просмотр, редактирование и удаление пользователя).
+- Это упрощает клиентскую интеграцию и соответствует лучшим REST-практикам.
+
 ## Запуск проекта
 
 ### 1. Клонировать репозиторий
@@ -61,3 +80,5 @@ java -jar target/user-service-spring.jar
 
 ### 7. Пример работы приложения
 ![img_1.png](readme-resources/img_1.png)
+![img_2.png](readme-resources/img_2.png)
+![img_3.png](readme-resources/img_3.png)

pom.xml

@@ -29,10 +29,23 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-validation</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-hateoas</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.9</version>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-data-jpa</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.postgresql</groupId>
             <artifactId>postgresql</artifactId>
@@ -43,6 +56,12 @@
             <artifactId>lombok</artifactId>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <version>5.2.0</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>
@@ -60,6 +79,7 @@
             <version>1.19.7</version>
             <scope>test</scope>
         </dependency>
+
     </dependencies>
     <build>
         <plugins>

readme-resources/img_2.png

@@ -8,33 +8,40 @@
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 
+import java.util.HashMap;
+import java.util.Map;
 import java.util.stream.Collectors;
 
-
 @RestControllerAdvice
 public class GlobalExceptionHandler {
 
     @ExceptionHandler(EntityNotFoundException.class)
-    public ResponseEntity<String> handleNotFound(EntityNotFoundException ex) {
-        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
+    public ResponseEntity<Map<String, Object>> handleNotFound(EntityNotFoundException ex) {
+        Map<String, Object> body = new HashMap<>();
+        body.put("error", "Not Found");
+        body.put("message", ex.getMessage());
+        body.put("status", HttpStatus.NOT_FOUND.value());
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
     }
 
     @ExceptionHandler(DataIntegrityViolationException.class)
-    public ResponseEntity<String> handleDuplicate(DataIntegrityViolationException ex) {
-        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Email already exists");
+    public ResponseEntity<Map<String, Object>> handleDuplicate(DataIntegrityViolationException ex) {
+        Map<String, Object> body = new HashMap<>();
+        body.put("error", "Bad Request");
+        body.put("message", "Email already exists");
+        body.put("status", HttpStatus.BAD_REQUEST.value());
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);
     }
 
     @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<String> handleValidation(MethodArgumentNotValidException ex) {
+    public ResponseEntity<Map<String, Object>> handleValidation(MethodArgumentNotValidException ex) {
         String message = ex.getBindingResult().getFieldErrors().stream()
                 .map(err -> err.getField() + ": " + err.getDefaultMessage())
                 .collect(Collectors.joining(", "));
-        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Validation error: " + message);
-    }
-
-    @ExceptionHandler(Exception.class)
-    public ResponseEntity<String> handleGeneric(Exception ex) {
-        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
-                .body("Unexpected error occurred");
+        Map<String, Object> body = new HashMap<>();
+        body.put("error", "Validation Error");
+        body.put("message", message);
+        body.put("status", HttpStatus.BAD_REQUEST.value());
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);
     }
-}
+}

readme-resources/img_3.png

@@ -3,8 +3,12 @@
 
 import myuserservice.dto.UserDto;
 import myuserservice.service.UserService;
+import myuserservice.hateoas.UserModelAssembler;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.hateoas.CollectionModel;
+import org.springframework.hateoas.EntityModel;
+import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -23,48 +27,61 @@ public class UserController {
 
     private static final Logger log = LoggerFactory.getLogger(UserController.class);
     private final UserService userService;
+    private final UserModelAssembler assembler;
 
-    public UserController(UserService userService) {
+    public UserController(UserService userService, UserModelAssembler assembler) {
         this.userService = userService;
+        this.assembler = assembler;
     }
 
     @PostMapping
-    public UserDto createUser (@Valid @RequestBody UserDto userDto) {
+    public EntityModel<UserDto> createUser (@Valid @RequestBody UserDto userDto) {
         log.info("POST /api/users — Запрос на создание пользователя: {}", userDto);
         UserDto created = userService.createUser(userDto);
         log.info("Пользователь создан:  id={}, email={}", created.getId(), created.getEmail());
-        return created;
+        return assembler.toModel(created) ;
     }
 
     @GetMapping("/{id}")
-    public UserDto getUserById(@PathVariable Long id) {
+    public EntityModel<UserDto> getUserById(@PathVariable Long id) {
         log.info("GET /api/users/{} — Запрос пользователя по id", id);
         UserDto user = userService.getUser(id);
         log.info("Пользователь найден: id={}, email={}", user.getId(), user.getEmail());
-        return user;
+        return assembler.toModel(user);
     }
 
     @GetMapping
-    public List<UserDto> getAllUsers() {
+    public CollectionModel<EntityModel<UserDto>> getAllUsers() {
         log.info("GET /api/users — Запрос списка всех пользователей");
         List<UserDto> users = userService.getAllUsers();
         log.info("Найдено пользователей: {}", users.size());
-        return users;
+
+        List<EntityModel<UserDto>> userModels = users.stream()
+                .map(assembler::toModel)
+                .toList();
+        return  CollectionModel.of(
+                userModels,
+                org.springframework.hateoas.server.mvc.WebMvcLinkBuilder
+                        .linkTo(org.springframework.hateoas.server.mvc.WebMvcLinkBuilder
+                                .methodOn(UserController.class).getAllUsers())
+                        .withSelfRel()
+        );
     }
 
     @PutMapping("/{id}")
-    public UserDto updateUser(@PathVariable Long id, @RequestBody UserDto userDto) {
+    public EntityModel<UserDto > updateUser(@PathVariable Long id, @RequestBody UserDto userDto) {
         log.info("PUT /api/users/{} — Запрос на обновление пользователя: {}", id, userDto);
         UserDto updated = userService.updateUser(id, userDto);
         log.info("Пользователь обновлён: {}", updated);
-        return updated;
+        return assembler.toModel(updated) ;
     }
 
     @DeleteMapping("/{id}")
-    public void deleteUser(@PathVariable Long id) {
+    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
         log.info("DELETE /api/users/{} — Запрос на удаление пользователя", id);
         userService.deleteUser(id);
         log.info("Пользователь с id={} удалён", id);
+        return ResponseEntity.noContent().build();
     }
 }
 

src/main/java/myuserservice/advice/GlobalExceptionHandler.java

@@ -1,7 +1,5 @@
 package myuserservice.dto;
 
-
-
 import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
@@ -10,12 +8,14 @@
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Size;
 import jakarta.validation.constraints.Email;
+import org.springframework.hateoas.server.core.Relation;
 
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
 @Builder
 
+@Relation(collectionRelation = "users")
 public class UserDto {
 
     private Long id;

src/main/java/myuserservice/controller/UserController.java

@@ -0,0 +1,23 @@
+package myuserservice.hateoas;
+
+import myuserservice.dto.UserDto;
+import myuserservice.controller.UserController;
+import org.springframework.hateoas.EntityModel;
+import org.springframework.hateoas.server.RepresentationModelAssembler;
+import org.springframework.stereotype.Component;
+
+import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;
+
+@Component
+public class UserModelAssembler implements RepresentationModelAssembler<UserDto, EntityModel<UserDto>> {
+
+    @Override
+    public EntityModel<UserDto> toModel(UserDto user) {
+        return EntityModel.of(user,
+                linkTo(methodOn(UserController.class).getUserById(user.getId())).withSelfRel(),
+                linkTo(methodOn(UserController.class).deleteUser(user.getId())).withRel("delete"),
+                linkTo(methodOn(UserController.class).updateUser(user.getId(), user)).withRel("update"),
+                linkTo(methodOn(UserController.class).getAllUsers()).withRel("all-users"));
+    }
+
+}

src/main/java/myuserservice/dto/UserDto.java

@@ -9,4 +9,3 @@ logging.level.org.hibernate.type.descriptor.sql=TRACE
 spring.http.encoding.charset=UTF-8
 spring.http.encoding.enabled=true
 spring.http.encoding.force=true
-