docs: include dto comments in openapi schemas

Tiku.Api/Contracts/AuthDtos.cs

@@ -4,74 +4,145 @@ using Tiku.Application.Auth;
 
 namespace Tiku.Api.Contracts;
 
+/// <summary>
+/// 手机号密码登录请求。
+/// </summary>
 public sealed class PasswordLoginDto
 {
+    /// <summary>
+    /// 租户 ID。登录阶段允许客户端指定租户，登录后的业务接口以 JWT/session 解析出的当前租户为准。
+    /// </summary>
     [Required]
     [Description("租户 ID。登录阶段允许客户端指定租户，登录后的业务接口以 JWT/session 解析出的当前租户为准。")]
     public Guid TenantId { get; set; }
 
+    /// <summary>
+    /// 手机号，建议前端提交规范化后的中国大陆手机号。
+    /// </summary>
     [Required]
     [StringLength(32)]
     [Description("手机号，建议前端提交规范化后的中国大陆手机号。")]
     public string Phone { get; set; } = string.Empty;
 
+    /// <summary>
+    /// 用户密码。
+    /// </summary>
     [Required]
     [StringLength(128, MinimumLength = 6)]
     [Description("用户密码。")]
     public string Password { get; set; } = string.Empty;
 }
 
+/// <summary>
+/// 短信验证码登录请求。
+/// </summary>
 public sealed class SmsLoginDto
 {
+    /// <summary>
+    /// 租户 ID。
+    /// </summary>
     [Required]
     [Description("租户 ID。")]
     public Guid TenantId { get; set; }
 
+    /// <summary>
+    /// 中国大陆手机号。
+    /// </summary>
     [Required]
     [StringLength(32)]
     [Description("中国大陆手机号。")]
     public string Phone { get; set; } = string.Empty;
 
+    /// <summary>
+    /// 收到的短信验证码。
+    /// </summary>
     [Required]
     [StringLength(12, MinimumLength = 4)]
     [Description("收到的短信验证码。")]
     public string Code { get; set; } = string.Empty;
 }
 
+/// <summary>
+/// OAuth code 登录请求。
+/// </summary>
 public sealed class OAuthCodeDto
 {
+    /// <summary>
+    /// 租户 ID。
+    /// </summary>
     [Required]
     [Description("租户 ID。")]
     public Guid TenantId { get; set; }
 
+    /// <summary>
+    /// OAuth 平台返回的一次性授权 code。
+    /// </summary>
     [Required]
     [StringLength(512)]
     [Description("OAuth 平台返回的一次性授权 code。")]
     public string Code { get; set; } = string.Empty;
 
+    /// <summary>
+    /// 客户端可提供的公开用户资料，不允许包含 token/secret。当前后端先保留模板字段，后续按业务需要逐步使用。
+    /// </summary>
     [Description("客户端可提供的公开用户资料，不允许包含 token/secret。当前后端先保留模板字段，后续按业务需要逐步使用。")]
     public Dictionary<string, object?>? Profile { get; set; }
 
+    /// <summary>
+    /// 微信用户资料语言，例如 zh_CN。当前微信小程序登录不会使用该字段。
+    /// </summary>
     [StringLength(20)]
     [Description("微信用户资料语言，例如 zh_CN。当前微信小程序登录不会使用该字段。")]
     public string? Lang { get; set; }
 }
 
+/// <summary>
+/// refresh token 请求。
+/// </summary>
 public sealed class RefreshSessionDto
 {
+    /// <summary>
+    /// refresh token。服务端只存储哈希，明文只返回给客户端一次。
+    /// </summary>
     [Required]
     [StringLength(2048)]
     [Description("refresh token。服务端只存储哈希，明文只返回给客户端一次。")]
     public string RefreshToken { get; set; } = string.Empty;
 }
 
+/// <summary>
+/// 登录成功后的用户、租户成员和令牌信息。
+/// </summary>
 public sealed class AuthenticatedUserDto
 {
+    /// <summary>
+    /// 用户 ID。
+    /// </summary>
     public Guid UserId { get; init; }
+
+    /// <summary>
+    /// 手机号。
+    /// </summary>
     public string? Phone { get; init; }
+
+    /// <summary>
+    /// 邮箱。
+    /// </summary>
     public string? Email { get; init; }
+
+    /// <summary>
+    /// 用户显示名称。
+    /// </summary>
     public string? Name { get; init; }
+
+    /// <summary>
+    /// 当前登录租户成员摘要。
+    /// </summary>
     public TenantMembershipSummary Tenant { get; init; } = default!;
+
+    /// <summary>
+    /// access token 和 refresh token。
+    /// </summary>
     public AuthTokenPair Tokens { get; init; } = default!;
 
     public static AuthenticatedUserDto FromApplication(AuthenticatedUser user)

Tiku.Api/Contracts/HealthDtos.cs

@@ -1,5 +1,11 @@
 namespace Tiku.Api.Contracts;
 
+/// <summary>
+/// 健康检查响应。
+/// </summary>
+/// <param name="Status">服务状态，例如 ok。</param>
+/// <param name="Service">服务名称。</param>
+/// <param name="CheckedAt">检查时间。</param>
 public sealed record HealthResponseDto(
     string Status,
     string Service,

Tiku.Api/Contracts/TenantDtos.cs

@@ -6,17 +6,34 @@ using Tiku.Domain.Tenancy;
 
 namespace Tiku.Api.Contracts;
 
+/// <summary>
+/// 租户解析查询参数。
+/// </summary>
 public sealed class TenantResolveQueryDto
 {
+    /// <summary>
+    /// 要解析的访问域名，例如 student.example.com。本地开发也可以直接传 localhost。
+    /// </summary>
     [StringLength(253)]
     [Description("要解析的访问域名，例如 student.example.com。本地开发也可以直接传 localhost。")]
     public string? Host { get; set; }
 
+    /// <summary>
+    /// 租户编码；本地开发或无独立域名时使用，例如 master。
+    /// </summary>
     [StringLength(100)]
     [Description("租户编码；本地开发或无独立域名时使用，例如 master。")]
     public string? TenantCode { get; set; }
 }
 
+/// <summary>
+/// 租户解析响应。
+/// </summary>
+/// <param name="Tenant">公开租户基础信息。</param>
+/// <param name="Branding">公开品牌配置。</param>
+/// <param name="Features">面向前端公开的功能开关。</param>
+/// <param name="AdminFeatures">面向管理端公开的功能开关。</param>
+/// <param name="PublicConfig">可公开的租户配置，不包含密钥或内部配置。</param>
 public sealed record TenantResolveResponseDto(
     PublicTenantDto Tenant,
     PublicTenantBrandingDto Branding,
@@ -24,6 +41,15 @@ public sealed record TenantResolveResponseDto(
     JsonElement AdminFeatures,
     JsonElement PublicConfig);
 
+/// <summary>
+/// 可公开给客户端的租户基础信息。
+/// </summary>
+/// <param name="Id">租户 ID。</param>
+/// <param name="Slug">租户编码。</param>
+/// <param name="Name">租户名称。</param>
+/// <param name="Status">租户状态。</param>
+/// <param name="Mode">租户模式。</param>
+/// <param name="Host">当前匹配到的访问域名。</param>
 public sealed record PublicTenantDto(
     Guid Id,
     string Slug,
@@ -32,6 +58,18 @@ public sealed record PublicTenantDto(
     TenantMode Mode,
     string? Host);
 
+/// <summary>
+/// 可公开给客户端的租户品牌信息。
+/// </summary>
+/// <param name="BrandName">品牌名称。</param>
+/// <param name="ShortName">品牌短名称。</param>
+/// <param name="Slogan">品牌标语。</param>
+/// <param name="LogoUrl">Logo 地址。</param>
+/// <param name="FaviconUrl">Favicon 地址。</param>
+/// <param name="ServiceWechat">客服微信。</param>
+/// <param name="ServiceAccountName">公众号或服务号名称。</param>
+/// <param name="Theme">公开主题配置。</param>
+/// <param name="PublicAssets">公开资源配置。</param>
 public sealed record PublicTenantBrandingDto(
     string? BrandName,
     string? ShortName,