feat: add auth dto and scalar templates

Tiku.Api/Controllers/AuthController.cs

@@ -1,17 +1,23 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Tiku.Application.Auth;
+using Tiku.Api.Contracts;
 
 namespace Tiku.Api.Controllers;
 
 [ApiController]
 [Route("api/auth")]
+[Produces("application/json")]
 public sealed class AuthController(IAuthService authService) : ControllerBase
 {
     [AllowAnonymous]
     [HttpPost("login/password")]
-    public async Task<ActionResult<AuthenticatedUser>> LoginWithPassword(
-        PasswordLoginHttpRequest request,
+    [EndpointSummary("手机号密码登录")]
+    [EndpointDescription("使用本地手机号和密码登录，签发 JWT access token 与数据库 refresh/session。")]
+    [ProducesResponseType<AuthenticatedUserDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status401Unauthorized)]
+    public async Task<ActionResult<AuthenticatedUserDto>> LoginWithPassword(
+        [FromBody] PasswordLoginDto request,
         CancellationToken cancellationToken)
     {
         var result = await authService.LoginWithPasswordAsync(
@@ -23,13 +29,17 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
                 Request.Headers.UserAgent.ToString()),
             cancellationToken);
 
-        return Ok(result);
+        return Ok(AuthenticatedUserDto.FromApplication(result));
     }
 
     [AllowAnonymous]
     [HttpPost("login/sms")]
-    public async Task<ActionResult<AuthenticatedUser>> LoginWithSms(
-        SmsLoginHttpRequest request,
+    [EndpointSummary("短信验证码登录")]
+    [EndpointDescription("校验已发送的登录用途短信验证码，成功后签发 JWT access token 与数据库 refresh/session。")]
+    [ProducesResponseType<AuthenticatedUserDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status401Unauthorized)]
+    public async Task<ActionResult<AuthenticatedUserDto>> LoginWithSms(
+        [FromBody] SmsLoginDto request,
         CancellationToken cancellationToken)
     {
         var result = await authService.LoginWithSmsAsync(
@@ -41,13 +51,18 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
                 Request.Headers.UserAgent.ToString()),
             cancellationToken);
 
-        return Ok(result);
+        return Ok(AuthenticatedUserDto.FromApplication(result));
     }
 
     [AllowAnonymous]
     [HttpPost("oauth/wechat")]
-    public async Task<ActionResult<AuthenticatedUser>> LoginWithWechatWeb(
-        WechatLoginHttpRequest request,
+    [EndpointSummary("微信网页 OAuth 登录")]
+    [EndpointDescription("使用微信网页授权 code 换取 openid/unionid，upsert 用户身份并创建应用会话。")]
+    [ProducesResponseType<AuthenticatedUserDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status503ServiceUnavailable)]
+    public async Task<ActionResult<AuthenticatedUserDto>> LoginWithWechatWeb(
+        [FromBody] OAuthCodeDto request,
         CancellationToken cancellationToken)
     {
         var result = await authService.LoginWithWechatWebAsync(
@@ -58,13 +73,18 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
                 Request.Headers.UserAgent.ToString()),
             cancellationToken);
 
-        return Ok(result);
+        return Ok(AuthenticatedUserDto.FromApplication(result));
     }
 
     [AllowAnonymous]
     [HttpPost("oauth/wechat-miniapp")]
-    public async Task<ActionResult<AuthenticatedUser>> LoginWithWechatMiniApp(
-        WechatLoginHttpRequest request,
+    [EndpointSummary("微信小程序登录")]
+    [EndpointDescription("使用小程序 wx.login 返回的 code 换取 openid/session_key，upsert 用户身份并创建应用会话。")]
+    [ProducesResponseType<AuthenticatedUserDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType<ProblemDetails>(StatusCodes.Status503ServiceUnavailable)]
+    public async Task<ActionResult<AuthenticatedUserDto>> LoginWithWechatMiniApp(
+        [FromBody] OAuthCodeDto request,
         CancellationToken cancellationToken)
     {
         var result = await authService.LoginWithWechatMiniAppAsync(
@@ -75,13 +95,15 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
                 Request.Headers.UserAgent.ToString()),
             cancellationToken);
 
-        return Ok(result);
+        return Ok(AuthenticatedUserDto.FromApplication(result));
     }
 
     [AllowAnonymous]
     [HttpPost("refresh")]
+    [EndpointSummary("刷新登录会话")]
+    [EndpointDescription("使用 refresh token 轮换数据库 session，并签发新的 access/refresh token。")]
     public async Task<ActionResult<AuthTokenPair>> Refresh(
-        RefreshHttpRequest request,
+        [FromBody] RefreshSessionDto request,
         CancellationToken cancellationToken)
     {
         var result = await authService.RefreshAsync(
@@ -96,8 +118,11 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
 
     [AllowAnonymous]
     [HttpPost("logout")]
+    [EndpointSummary("退出登录")]
+    [EndpointDescription("撤销 refresh token 对应的数据库 session；session 校验开启时，旧 access token 也会被拒绝。")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
     public async Task<IActionResult> Logout(
-        RefreshHttpRequest request,
+        [FromBody] RefreshSessionDto request,
         CancellationToken cancellationToken)
     {
         await authService.LogoutAsync(
@@ -112,19 +137,3 @@ public sealed class AuthController(IAuthService authService) : ControllerBase
         return HttpContext.Connection.RemoteIpAddress?.ToString();
     }
 }
-
-public sealed record PasswordLoginHttpRequest(
-    Guid TenantId,
-    string Phone,
-    string Password);
-
-public sealed record SmsLoginHttpRequest(
-    Guid TenantId,
-    string Phone,
-    string Code);
-
-public sealed record WechatLoginHttpRequest(
-    Guid TenantId,
-    string Code);
-
-public sealed record RefreshHttpRequest(string RefreshToken);