文档相关修复

Author: xrain0610

Attributes/SimApiDocAttribute.cs

@@ -1,39 +1,105 @@
-using System;
+using System;
 using Swashbuckle.AspNetCore.Annotations;
 
 namespace SimApi.Attributes;
 
 /// <summary>
-/// 快捷自定义接口文档类
+/// 快捷自定义接口文档类(所有参数均可省略, 支持命名参数)。
+/// 对应仓颉版 SimApiDoc:
+///   tags        → 接口标签(逗号分隔, 如 "认证,用户")
+///   name        → API 名称(映射到 Summary, 作为文档接口标题)
+///   description → API 详细描述
+///   groupNames  → 所属文档组(逗号分隔, 如 "api,admin"; "*" 表示所有文档; null/空 → 仅默认 "api" 文档)
+///   ignore      → true 时不出现在任何文档中(路由不受影响)
+/// 写法示例:
+///   [SimApiDoc("认证", "登录")]                      位置参数(保持旧版兼容)
+///   [SimApiDoc(tags: "认证", name: "登录", description: "...")]
+///   [SimApiDoc(groupNames: "api,admin")]             仅指定文档组
+///   [SimApiDoc(GroupNames = "*", Ignore = false)]    属性命名参数
+///   [SimApiDoc]                                      全部默认(可标在类上, 仅用 Ignore/GroupNames 等)
+/// 属性命名参数优先于构造命名参数。
 /// </summary>
 [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
 public class SimApiDocAttribute : SwaggerOperationAttribute
 {
     /// <summary>
-    /// 定义接口说明
+    /// 出现在所有文档组中的通配符
     /// </summary>
-    /// <param name="tags">接口分组列表</param>
+    public const string AllGroups = "*";
+
+    /// <summary>
+    /// 接口所属的文档组(逗号分隔, 如 "api,admin"); "*" 表示所有文档; null/空 表示未分组(仅默认 "api" 文档)
+    /// </summary>
+    public string? GroupNames { get; set; }
+
+    /// <summary>
+    /// 为 true 时该接口不出现在任何文档中(不影响路由)
+    /// </summary>
+    public bool Ignore { get; set; }
+
+    /// <summary>
+    /// 定义接口说明(全部可选)
+    /// </summary>
+    /// <param name="tags">接口标签, 逗号分隔, 如 "认证,用户"</param>
     /// <param name="name">接口名称</param>
     /// <param name="description">接口描述</param>
-    public SimApiDocAttribute(string[] tags, string name, string? description = null)
+    /// <param name="groupNames">所属文档组, 逗号分隔; "*" 表示所有文档</param>
+    /// <param name="ignore">true 时不出现在任何文档</param>
+    public SimApiDocAttribute(string? tags = null, string? name = null, string? description = null,
+        string? groupNames = null, bool ignore = false)
     {
-        Tags = tags;
-        Summary = name;
-        if (description != null)
-        {
-            Description = description;
-        }
-        // Consumes = new[] {"application/json"};
-        // Produces = new[] {"application/json"};
+        Apply(tags, name, description, groupNames, ignore);
     }
 
     /// <summary>
-    /// 定义接口说明
+    /// 定义接口说明(标签以数组传入)
     /// </summary>
-    /// <param name="tag">接口分组</param>
+    /// <param name="tags">接口标签列表</param>
     /// <param name="name">接口名称</param>
     /// <param name="description">接口描述</param>
-    public SimApiDocAttribute(string tag, string name, string? description = null) : this([tag], name, description)
+    /// <param name="groupNames">所属文档组, 逗号分隔; "*" 表示所有文档</param>
+    /// <param name="ignore">true 时不出现在任何文档</param>
+    public SimApiDocAttribute(string[] tags, string? name = null, string? description = null,
+        string? groupNames = null, bool ignore = false)
+    {
+        Apply(tags, name, description, groupNames, ignore);
+    }
+
+    private void Apply(string? tags, string? name, string? description,
+        string? groupNames, bool ignore)
+    {
+        if (!string.IsNullOrWhiteSpace(tags))
+        {
+            Tags = tags.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        }
+
+        ApplyCore(name, description, groupNames, ignore);
+    }
+
+    private void Apply(string[] tags, string? name, string? description,
+        string? groupNames, bool ignore)
     {
+        if (tags is { Length: > 0 })
+        {
+            Tags = tags;
+        }
+
+        ApplyCore(name, description, groupNames, ignore);
+    }
+
+    private void ApplyCore(string? name, string? description, string? groupNames, bool ignore)
+    {
+        if (!string.IsNullOrEmpty(name))
+        {
+            Summary = name;
+        }
+
+        if (!string.IsNullOrEmpty(description))
+        {
+            Description = description;
+        }
+
+        GroupNames = groupNames;
+        Ignore = ignore;
     }
-}
+}

Configurations/SimApiDocOptions.cs

@@ -6,7 +6,7 @@ namespace SimApi.Configurations;
 /// <summary>
 /// 文档组配置
 /// </summary>
-public class SimApiDocGroupOption(string id, string name, string description = "")
+public class SimApiDocGroupOption(string id, string name, string description = "", bool isDefault = false)
 {
     /// <summary>
     /// 文档标识
@@ -22,6 +22,11 @@ public class SimApiDocGroupOption(string id, string name, string description = "
     /// 文档描述
     /// </summary>
     public string Description { get; set; } = description!;
+
+    /// <summary>
+    /// 是否为默认文档组: 未标注分组的接口全部归入此文档组
+    /// </summary>
+    public bool IsDefault { get; set; } = isDefault;
 }
 
 /// <summary>
@@ -50,14 +55,20 @@ public class SimApiDocOptions
     /// </summary>
     public SimApiDocGroupOption[] ApiGroups { get; set; } =
     [
-        new("api", "Api", "Api接口文档")
+        new("api", "Api", "Api接口文档", isDefault: true)
     ];
 
     /// <summary>
     /// 授权配置
     /// </summary>
     public SimApiAuthOption ApiAuth { get; set; } = new();
 
+    /// <summary>
+    /// 接口文档页面访问前缀, 默认 "docs"。
+    /// 访问 /docs 即打开文档页面, JSON 地址为 /docs/{文档组Id}.json
+    /// </summary>
+    public string UrlPrefix { get; set; } = "docs";
+
     /// <summary>
     /// 文档页面标题
     /// </summary>

Controllers/SimApiAuthController.cs

@@ -11,7 +11,7 @@ public class SimApiAuthController(SimApiAuth auth) : SimApiBaseController
     /// 退出登陆
     /// </summary>
     /// <returns></returns>
-    [HttpPost, SimApiDoc("认证", "退出登陆")]
+    [HttpPost, SimApiDoc("认证", "退出登陆",groupNames: "*")]
     public void Logout()
     {
         if (Request.Headers.TryGetValue("Token", out var value))

Controllers/SimApiBuiltInRoutes.cs

@@ -0,0 +1,48 @@
+using System;
+using System.Collections.Generic;
+using SimApi.Configurations;
+
+namespace SimApi.Controllers;
+
+/// <summary>
+/// SimApi 内置端点路由表中的一项。
+/// </summary>
+public sealed record SimApiBuiltInRoute(
+    string RouteName,
+    string Controller,
+    string Action,
+    string[] HttpMethods,
+    string Path);
+
+/// <summary>
+/// SimApi 内置端点路由表 —— 路径的唯一配置处。
+/// UseSimApi 用它注册约定路由(动态路由)，
+/// SimApiBuiltInRoutesDescriptionProvider 用它生成文档条目。
+/// 某项路径为 null / 空时该端点既不注册路由、也不出现在文档中。
+/// </summary>
+public static class SimApiBuiltInRoutes
+{
+    public static IEnumerable<SimApiBuiltInRoute> Get(SimApiRouteOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (!string.IsNullOrEmpty(options.UserInfoRoute))
+        {
+            yield return new SimApiBuiltInRoute(
+                "UserInfo", "SimApiCommon", "UserInfo", ["POST"], options.UserInfoRoute);
+        }
+
+        if (!string.IsNullOrEmpty(options.LogoutRoute))
+        {
+            yield return new SimApiBuiltInRoute(
+                "Logout", "SimApiAuth", "Logout", ["POST"], options.LogoutRoute);
+        }
+
+        if (!string.IsNullOrEmpty(options.WebConfigRoute))
+        {
+            // 控制器动作同时标注了 HttpGet/HttpPost
+            yield return new SimApiBuiltInRoute(
+                "WebConfig", "SimApiCommon", "WebConfig", ["GET", "POST"], options.WebConfigRoute);
+        }
+    }
+}

Controllers/SimApiBuiltInRoutesDescriptionProvider.cs

@@ -0,0 +1,117 @@
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
+using Microsoft.Extensions.DependencyInjection;
+using SimApi.Configurations;
+
+namespace SimApi.Controllers;
+
+/// <summary>
+/// 将 SimApiRouteOptions 动态配置的内置约定路由(UserInfo / Logout / WebConfig)
+/// 翻译成 ApiDescription, 使它们能像属性路由接口一样出现在 Swagger 文档中:
+/// 请求/响应 schema 由 Swashbuckle 自动分析, 方法上已有的 [SimApiDoc] 注解自动生效。
+/// 路径为 null / 空 的端点在此一并跳过(与路由注册保持一致)。
+/// </summary>
+public class SimApiBuiltInRoutesDescriptionProvider(
+    IServiceProvider services,
+    SimApiOptions options) : IApiDescriptionProvider
+{
+    /// <summary>
+    /// 默认 provider(DefaultApiDescriptionProvider)的 Order 为 -1000, 位于其后执行。
+    /// </summary>
+    public int Order => -900;
+
+    public void OnProvidersExecuting(ApiDescriptionProviderContext context)
+    {
+    }
+
+    public void OnProvidersExecuted(ApiDescriptionProviderContext context)
+    {
+        var modelMetadata = services.GetService<IModelMetadataProvider>();
+
+        foreach (var route in SimApiBuiltInRoutes.Get(options.SimApiRouteOptions))
+        {
+            var action = context.Actions.OfType<ControllerActionDescriptor>()
+                .FirstOrDefault(a =>
+                    string.Equals(a.ControllerName, route.Controller, StringComparison.Ordinal) &&
+                    string.Equals(a.ActionName, route.Action, StringComparison.Ordinal));
+            if (action is null)
+            {
+                continue;
+            }
+
+            // 若该动作已被属性路由 / 其他 provider 收录, 跳过避免重复
+            if (context.Results.Any(d => ReferenceEquals(d.ActionDescriptor, action)))
+            {
+                continue;
+            }
+
+            foreach (var httpMethod in route.HttpMethods)
+            {
+                context.Results.Add(CreateDescription(action, route, httpMethod, modelMetadata));
+            }
+        }
+    }
+
+    private static ApiDescription CreateDescription(
+        ControllerActionDescriptor action,
+        SimApiBuiltInRoute route,
+        string httpMethod,
+        IModelMetadataProvider? modelMetadata)
+    {
+        var apiDescription = new ApiDescription
+        {
+            ActionDescriptor = action,
+            HttpMethod = httpMethod,
+            RelativePath = route.Path.TrimStart('/')
+        };
+
+        // 输入: 按真实方法参数翻译(内置端点均为零参, 此处保证将来加参也可分析)
+        foreach (var parameter in action.Parameters)
+        {
+            var parameterDescription = new ApiParameterDescription
+            {
+                Name = parameter.Name,
+                Type = parameter.ParameterType,
+                ParameterDescriptor = parameter,
+                Source = parameter.BindingInfo?.BindingSource ?? BindingSource.Body,
+                IsRequired = true
+            };
+            if (modelMetadata is not null)
+            {
+                parameterDescription.ModelMetadata = modelMetadata.GetMetadataForType(parameter.ParameterType);
+            }
+
+            apiDescription.ParameterDescriptions.Add(parameterDescription);
+        }
+
+        // 输出: 方法返回类型 => 200 + json
+        var returnType = Unwrap(action.MethodInfo.ReturnType);
+        if (returnType != typeof(void))
+        {
+            var responseType = new ApiResponseType
+            {
+                StatusCode = 200,
+                Type = returnType,
+                IsDefaultResponse = true
+            };
+            if (modelMetadata is not null)
+            {
+                responseType.ModelMetadata = modelMetadata.GetMetadataForType(returnType);
+            }
+
+            responseType.ApiResponseFormats.Add(new ApiResponseFormat { MediaType = "application/json" });
+            apiDescription.SupportedResponseTypes.Add(responseType);
+        }
+
+        return apiDescription;
+    }
+
+    private static Type Unwrap(Type type) =>
+        type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Task<>)
+            ? type.GetGenericArguments()[0]
+            : type;
+}

Controllers/SimApiCommonController.cs

@@ -18,7 +18,7 @@ public class SimApiCommonController(SimApiOptions simApiOptions) : SimApiBaseCon
     /// <param name="code">错误代码</param>
     /// <returns></returns>
     [HttpGet("exception/{code:int}")]
-    [ApiExplorerSettings(IgnoreApi = true)]
+    [SimApiDoc(ignore: true)]
     public void ExceptionHandler(int code)
     {
         Error(code);
@@ -29,6 +29,7 @@ public void ExceptionHandler(int code)
     /// </summary>
     /// <returns></returns>
     [HttpPost, HttpGet]
+    [HttpPost, SimApiDoc("公共", "获取自定义配置",groupNames: "*")]
     public Dictionary<string, object> WebConfig()
     {
         var resp = simApiOptions.WebConfig!.ToDictionary();
@@ -49,6 +50,6 @@ public Dictionary<string, object> WebConfig()
     /// 获取已登录用户信息
     /// </summary>
     /// <returns></returns>
-    [HttpPost, SimApiAuth, SimApiDoc("认证", "获取已登录用户信息")]
+    [HttpPost, SimApiAuth, SimApiDoc("认证", "获取已登录用户信息",groupNames: "*")]
     public SimApiLoginItem UserInfo() => LoginInfo;
 }

Helpers/SimApiUtil.cs

@@ -28,7 +28,7 @@ public static class SimApiUtil
     {
         // ReferenceHandler = ReferenceHandler.Preserve,
         Encoder = JavaScriptEncoder.Create(UnicodeRanges.All),
-        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
         // DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
     };