feat: добавил интеграционные тесты

backend/UniVerse.Api/Controllers/AchievementsController.cs

@@ -5,31 +5,87 @@ using UniVerse.Application.Interfaces;
 
 namespace UniVerse.Api.Controllers;
 
+/// <summary>Управление определениями достижений системы геймификации.</summary>
 [ApiController]
 [Route("api/v1/achievements")]
 [Authorize]
+[Produces("application/json")]
 public class AchievementsController : ControllerBase
 {
     private readonly IAchievementService _achievements;
+
     public AchievementsController(IAchievementService achievements) => _achievements = achievements;
 
+    /// <summary>Получить список всех достижений.</summary>
+    /// <remarks>Возвращает определения достижений (без информации о получении конкретным пользователем).
+    /// Для достижений конкретного пользователя используйте GET /api/v1/users/{id}/achievements.</remarks>
+    /// <response code="200">Список достижений.</response>
+    /// <response code="401">Требуется аутентификация.</response>
     [HttpGet]
+    [ProducesResponseType(typeof(List<AchievementDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
     public async Task<ActionResult> GetAll() => Ok(await _achievements.GetAllAsync());
 
+    /// <summary>Получить достижение по ID.</summary>
+    /// <param name="id">ID достижения.</param>
+    /// <response code="200">Данные достижения.</response>
+    /// <response code="401">Требуется аутентификация.</response>
+    /// <response code="404">Достижение не найдено.</response>
     [HttpGet("{id:int}")]
+    [ProducesResponseType(typeof(AchievementDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<AchievementDto>> Get(int id) => Ok(await _achievements.GetByIdAsync(id));
 
+    /// <summary>Создать новое достижение.</summary>
+    /// <remarks>Только Admin. Достижения автоматически присваиваются студентам при выполнении условий.</remarks>
+    /// <param name="req">Название, описание, иконка, награда в XP/монетах и условие получения.</param>
+    /// <response code="201">Достижение создано.</response>
+    /// <response code="401">Требуется аутентификация.</response>
+    /// <response code="403">Требуется роль Admin.</response>
     [Authorize(Roles = "Admin")]
     [HttpPost]
+    [ProducesResponseType(typeof(AchievementDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
     public async Task<ActionResult<AchievementDto>> Create([FromBody] CreateAchievementRequest req) =>
         CreatedAtAction(nameof(Get), new { id = 0 }, await _achievements.CreateAsync(req));
 
+    /// <summary>Обновить достижение по ID.</summary>
+    /// <remarks>Только Admin.</remarks>
+    /// <param name="id">ID достижения.</param>
+    /// <param name="req">Обновляемые поля достижения.</param>
+    /// <response code="200">Обновлённые данные достижения.</response>
+    /// <response code="401">Требуется аутентификация.</response>
+    /// <response code="403">Требуется роль Admin.</response>
+    /// <response code="404">Достижение не найдено.</response>
     [Authorize(Roles = "Admin")]
     [HttpPut("{id:int}")]
+    [ProducesResponseType(typeof(AchievementDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<AchievementDto>> Update(int id, [FromBody] UpdateAchievementRequest req) =>
         Ok(await _achievements.UpdateAsync(id, req));
 
+    /// <summary>Удалить достижение по ID.</summary>
+    /// <remarks>
+    /// Только Admin. Удаление не отзывает достижение у уже получивших его пользователей.
+    /// </remarks>
+    /// <param name="id">ID достижения.</param>
+    /// <response code="204">Достижение удалено.</response>
+    /// <response code="401">Требуется аутентификация.</response>
+    /// <response code="403">Требуется роль Admin.</response>
+    /// <response code="404">Достижение не найдено.</response>
     [Authorize(Roles = "Admin")]
     [HttpDelete("{id:int}")]
-    public async Task<IActionResult> Delete(int id) { await _achievements.DeleteAsync(id); return NoContent(); }
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Delete(int id)
+    {
+        await _achievements.DeleteAsync(id);
+        return NoContent();
+    }
 }