docs: include dto comments in openapi schemas

Tiku.IntegrationTests/Api/OpenApiDocumentationTests.cs

@@ -0,0 +1,67 @@
+using System.Net;
+using System.Text.Json;
+
+namespace Tiku.IntegrationTests.Api;
+
+public sealed class OpenApiDocumentationTests
+{
+    [Fact]
+    public async Task Openapi_includes_request_schema_property_descriptions()
+    {
+        await using var factory = new ApiTestFactory();
+        using var client = factory.CreateClient();
+
+        using var response = await client.GetAsync("/openapi/v1.json");
+        var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.Contains(
+            "租户 ID",
+            GetSchemaPropertyDescription(document, "PasswordLoginDto", "tenantId"),
+            StringComparison.Ordinal);
+        Assert.Contains(
+            "手机号",
+            GetSchemaPropertyDescription(document, "PasswordLoginDto", "phone"),
+            StringComparison.Ordinal);
+        Assert.Contains(
+            "refresh token",
+            GetSchemaPropertyDescription(document, "RefreshSessionDto", "refreshToken"),
+            StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task Openapi_includes_response_schema_property_descriptions()
+    {
+        await using var factory = new ApiTestFactory();
+        using var client = factory.CreateClient();
+
+        using var response = await client.GetAsync("/openapi/v1.json");
+        var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.Contains(
+            "access token",
+            GetSchemaPropertyDescription(document, "AuthTokenPair", "accessToken"),
+            StringComparison.OrdinalIgnoreCase);
+        Assert.Contains(
+            "租户名称",
+            GetSchemaPropertyDescription(document, "PublicTenantDto", "name"),
+            StringComparison.Ordinal);
+    }
+
+    private static string GetSchemaPropertyDescription(
+        JsonDocument document,
+        string schemaName,
+        string propertyName)
+    {
+        return document
+            .RootElement
+            .GetProperty("components")
+            .GetProperty("schemas")
+            .GetProperty(schemaName)
+            .GetProperty("properties")
+            .GetProperty(propertyName)
+            .GetProperty("description")
+            .GetString() ?? string.Empty;
+    }
+}