@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/06-1/350/246/217/347/257/204/345/214/226/346/216/245/345/217/243.md

@@ -0,0 +1,1458 @@
+# 6. 规范化接口文档
+
+## 📝 模块更新日志
+
+*(详见 Furion 官方 Changelog)*
+
+---
+
+## 6.1 什么是接口文档
+
+在现在移动为王、多端互辅、前端百花齐放的开放时代，不再是一人包揽式开发，大家各司其职，后端工程师负责接口开发，前端负责接口联调，也就是互联网现在流行的前后端分离架构。
+
+所以就需要由前后端工程师共同定义接口，编写接口文档，之后大家按照这个接口文档进行开发、维护及开放给第三方。
+
+## 6.2 为什么要写接口文档
+
+- 能够让前端开发与后台开发人员更好的配合，提高工作效率
+- 项目迭代或者项目人员更迭时，方便后期人员查看和维护
+- 方便测试人员进行接口测试
+
+## 6.3 为什么需要规范化文档
+
+由于每个公司后端人员技术参差不齐，技术文档能力也不例外，导致接口定义及文档五花八门，不同项目或不同公司对接极其困难，而且体验糟糕。所以，无规矩不成方圆，为了开发人员间更好的配合，迫切需要整理出一套规范。
+
+通常接口规范分为六个部分：
+
+### 6.3.1 协议规范
+
+为了确保不同系统/模块间的数据交互，需要事先约定好通讯协议，如：TCP、HTTP、HTTPS 协议。为了确保数据交互安全，建议使用 HTTPS 协议。
+
+### 6.3.2 接口路径规范
+
+作为接口路径，为了方便清晰的区分来自不同的系统，可以采用不同系统/模块名作为接口路径前缀，如：支付模块 `/pay/xxx`，订单模块 `/order/xxx`。
+
+### 6.3.3 版本控制规范
+
+为了便于后期接口的升级和维护，建议在接口路径中加入版本号，便于管理，实现接口多版本的可维护性。如：接口路径中添加类似 `v1`、`v2` 等版本号。
+
+### 6.3.4 接口命名规范
+
+和 C# 命名规范一样，好的、统一的接口命名规范，不仅可以增强其可读性，而且还会减少很多不必要的口头/书面上的解释。可使用"驼峰命名法"按照实现接口的业务类型、业务场景等命名。
+
+常见命名方式：
+
+**接口名称动词前/后缀化：** 接口名称以接口数据操作的动词为前/后缀，常见动词有：Add、Delete、Update、Query、Get、Send、Save、Detail、List 等，如：新建用户 `AddUser`、查询订单详情 `QueryOrderDetail`。
+
+**接口名称动词 + 请求方式：** 接口路径中包含具体接口名称的名词，接口数据操作动作以 HTTP 请求方式来区分：
+
+| 方法 | 说明 |
+|------|------|
+| GET | 从服务器取出资源（一项或多项） |
+| POST | 在服务器新建一个资源 |
+| PUT | 在服务器更新资源（客户端提供改变后的完整资源） |
+| PATCH | 在服务器更新资源（客户端提供改变的属性） |
+| DELETE | 从服务器删除资源 |
+
+### 6.3.5 请求参数规范
+
+- **请求方式**：按照 GET、POST、PUT 等含义定义，避免出现不一致现象
+- **请求头**：请求头根据项目需求添加配置参数。如：请求数据格式 `accept=application/json` 等。如有需要，请求头可根据项目需求要求传入用户 token、唯一验签码等加密数据
+- **请求参数/请求体**：请求参数字段，尽可能与数据库表字段、对象属性名等保持一致
+
+### 6.3.6 返回数据规范
+
+统一规范返回数据的格式，以 JSON 格式为例。返回数据应包含：返回状态码、返回状态信息、具体数据。返回数据中的状态码、状态信息，常指具体的业务状态，不建议和 HTTP 状态码混在一起。HTTP 状态码和 JSON 结果中的状态码，并存尚可，用于体现不同维度的状态。
+
+---
+
+## 6.4 什么是 Swagger
+
+Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
+
+通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过 Swagger 衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。
+
+总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。
+
+---
+
+## 6.5 Swagger 使用
+
+Furion 框架提供了非常方便且灵活的 Swagger 配置，无需增加额外学习成本。
+
+### 6.5.1 注册服务
+
+> **小提示**：`.AddInject[XXX]()` 已经包含了 `.AddSpecificationDocuments()` 注册，无需再次注册。`.UseInject()` 已经包含了 `.UseSpecificationDocuments()` 注册，无需再次注册。
+
+```csharp
+// Furion.Web.Core\Startup.cs
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace Furion.Web.Core
+{
+    [AppStartup(800)]
+    public sealed class FurWebCoreStartup : AppStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddSpecificationDocuments();
+            services.AddControllers();
+        }
+
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            // Other Codes
+
+            app.UseSpecificationDocuments();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapControllers();
+            });
+        }
+    }
+}
+```
+
+> **小知识**：`services.AddSpecificationDocuments()` 通常和 `.AddDynamicApiControllers()` 成对出现。
+
+### 6.5.2 默认地址
+
+在 Furion 框架中，默认规范化文档地址为 `/api` 目录，支持自定义配置。
+
+可以通过两种方式配置：
+
+**方式一：`app.UseInject("路由")`**
+
+```csharp
+app.UseInject("testapi"); // 那么 /testapi 就是规范化地址
+```
+
+**方式二：配置文件**
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "RoutePrefix": "testapi"
+  }
+}
+```
+
+> 配置文件优先级大于 `UseInject()` 方式。
+
+### 6.5.3 默认分组
+
+Furion 框架中默认分组名为 `Default`，支持自定义配置：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "DefaultGroupName": "MyGroup"
+  }
+}
+```
+
+### 6.5.4 文档注释
+
+规范化文档默认扫描 `Furion.Application`、`Furion.Web.Core`、`Furion.Web.Entry` 三个程序集 `.xml` 注释文件，支持自定义配置。
+
+只支持 `///` 标识的注释语法，如：类、方法、属性、参数、返回值、验证特性。
+
+```csharp
+using Furion.DynamicApiController;
+
+namespace Furion.Application
+{
+    /// <summary>
+    /// 类注释
+    /// </summary>
+    public class FurionAppService : IDynamicApiController
+    {
+        /// <summary>
+        /// 方法注释
+        /// </summary>
+        /// <returns></returns>
+        public string Get()
+        {
+            return nameof(Furion);
+        }
+
+        /// <summary>
+        /// 带 ID 参数的方法注释
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
+        public int Get(int id)
+        {
+            return id;
+        }
+
+        [DisplayName("生成注释")] // Furion 4.9.2.3+ 版本支持
+        public void SomeMethod()
+        {
+        }
+    }
+}
+```
+
+> **小提示**：如果文档注释没有显示，请检查项目 **属性 → 生成 → 输出** 中 XML 文档是否配置输出路径。注意：只有不带路径的 `【项目名称.xml】` 才会自动加载。
+
+```xml
+<PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <DocumentationFile>Furion.Application.xml</DocumentationFile>
+</PropertyGroup>
+```
+
+> **特别说明**：Debug 模式下和 Release 模式下的注释文件是不通用的，所以导致很多开发者发布到服务器上发现没有显示注释。只需要在 Visual Studio 中切换 Debug 模式为 Release，然后重新配置一次即可。
+
+### 6.5.5 多分组支持
+
+多分组是一个系统中必备功能，我们可以将系统划分为多个模块，每个模块都独立的 api 配置。
+
+```csharp
+using Furion.DynamicApiController;
+
+namespace Furion.Application
+{
+    [ApiDescriptionSettings("Group1")]
+    public class FurionAppService : IDynamicApiController
+    {
+        /// <summary>
+        /// 随父类 Group1 分组
+        /// </summary>
+        public string Post()
+        {
+            return nameof(Furion);
+        }
+
+        /// <summary>
+        /// 在 Group1、Group3 都有我
+        /// </summary>
+        [ApiDescriptionSettings("Group1", "Group3")]
+        public string Get()
+        {
+            return nameof(Furion);
+        }
+
+        /// <summary>
+        /// 我只在 Group2 出现
+        /// </summary>
+        [ApiDescriptionSettings("Group2")]
+        public int Get(int id)
+        {
+            return id;
+        }
+    }
+}
+```
+
+### 6.5.6 多分组排序
+
+通过分组名称添加 `@整数` 进行排序：
+
+```csharp
+[ApiDescriptionSettings("Group1@1")]
+public class FurionAppService : IDynamicApiController
+{
+    public string Post()
+    {
+        return nameof(Furion);
+    }
+
+    [ApiDescriptionSettings("Group1", "Group3")]
+    public string Get()
+    {
+        return nameof(Furion);
+    }
+
+    [ApiDescriptionSettings("Group@2")]
+    public int Get(int id)
+    {
+        return id;
+    }
+}
+```
+
+可以通过在分组名后面添加 `@整数` 进行排序，**整数越大排前面**。如果分组名称多次指定且多次指定了 `@整数`，则自动取该分组最大的整数进行排序。
+
+> **排序说明**：分组默认排序 `Order` 为 0。如果同时配置了 `@整数` 和 `appsettings.json` 配置文件，那么优先采用 `appsettings.json` 中的 `Order`。
+
+### 6.5.7 多分组信息配置
+
+Furion 框架提供了可通过 `appsettings.json` 配置分组信息：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "GroupOpenApiInfos": [
+      {
+        "Group": "Group1",
+        "Title": "分组标题",
+        "Description": "这里是分组描述",
+        "Version": "版本号",
+        "TermsOfService": "https://furion.net",
+        "Contact": {
+          "Name": "百小僧",
+          "Url": "https://gitee.com/monksoul",
+          "Email": "monksoul@outlook.com"
+        },
+        "License": {
+          "Name": "MIT",
+          "Url": "https://gitee.com/dotnetchina/Furion/blob/alpha/LICENSE"
+        }
+      }
+    ]
+  }
+}
+```
+
+**版本说明**（Furion 4.8.8.26+）：自该版本开始，可以在任何配置文件中添加 `[openapi:分组名]` 作为 Key 进行配置：
+
+```json
+{
+  "[openapi:Group1]": {
+    "Title": "我是自定义的标题",
+    "Order": 10,
+    "Description": "我是自定义的描述",
+    "Version": "2.0.0",
+    "TermsOfService": "https://furion.net",
+    "Contact": {
+      "Name": "Furion.NET",
+      "Url": "https://gitee.com/monksoul",
+      "Email": "support@furion.net"
+    },
+    "License": {
+      "Name": "MIT",
+      "Url": "https://gitee.com/dotnetchina/Furion/blob/v4/LICENSE"
+    }
+  }
+}
+```
+
+> 如果两种方式同时配置，那么 `GroupOpenApiInfos` 中的属性值只有在 `[openapi:分组名]` 配置中存在才会覆盖，不存在则保留。
+
+### 6.5.8 控制器和方法排序
+
+框架提供了 `[ApiDescriptionSettings]` 特性的 `Order` 属性，其值越大排序越靠前：
+
+```csharp
+[ApiDescriptionSettings(Order = 10)]
+public class FurionAppService : IDynamicApiController
+{
+    public string Post()
+    {
+        return nameof(Furion);
+    }
+
+    [ApiDescriptionSettings(Order = 5)]
+    public string Get()
+    {
+        return nameof(Furion);
+    }
+
+    [ApiDescriptionSettings(Order = 4)]
+    public int Get(int id)
+    {
+        return id;
+    }
+}
+
+[ApiDescriptionSettings(Order = 9)]
+public class Furion2AppService : IDynamicApiController
+{
+    // ...
+}
+```
+
+> **排序说明**：最终输出到 Swagger 界面时，`FurionAppService` 比 `Furion2AppService` 靠前，而 `FurionAppService` 中定义的方法排序时：`Get > Get(int id) > Post`。
+
+### 6.5.9 组中组（标签）
+
+`Tag` 配置主要用于配置 Swagger 标签分组信息及合并标签，也就是"组中组"：
+
+```csharp
+[ApiDescriptionSettings(Tag = "分组一")]
+public class FurionAppService : IDynamicApiController
+{
+    public string Get()
+    {
+        return nameof(Furion);
+    }
+
+    public int Get(int id)
+    {
+        return id;
+    }
+}
+
+[ApiDescriptionSettings(Tag = "分组二")]
+public class TestAppService : IDynamicApiController
+{
+    public string Get()
+    {
+        return nameof(Furion);
+    }
+
+    public int Get(int id)
+    {
+        return id;
+    }
+}
+```
+
+> **小知识**：如果 `Tag` 名字一样，则会自动合并，否则只是命名。
+
+### 6.5.10 默认展开所有文档
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "DocExpansionState": "Full"
+  }
+}
+```
+
+`DocExpansionState` 配置说明：
+
+| 值 | 说明 |
+|------|------|
+| `List` | 列表式（展开子类），默认值 |
+| `Full` | 完全展开 |
+| `None` | 列表式（不展开子类） |
+
+### 6.5.11 配置文档标题
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "DocumentTitle": "我是自定义标题"
+  }
+}
+```
+
+### 6.5.12 授权控制
+
+新版本 Furion 已经默认启用了 Bearer Token 授权配置，无需手动配置，如需手动配置：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "EnableAuthorized": true,
+    "SecurityDefinitions": [
+      {
+        "Id": "Bearer",
+        "Type": "Http",
+        "Name": "Authorization",
+        "Description": "JWT Authorization header using the Bearer scheme.",
+        "BearerFormat": "JWT",
+        "Scheme": "bearer",
+        "In": "Header",
+        "Requirement": {
+          "Scheme": {
+            "Reference": { "Id": "Bearer", "Type": "SecurityScheme" },
+            "Accesses": []
+          }
+        }
+      },
+      {
+        "Id": "basic",
+        "Type": "Http",
+        "Name": "basic",
+        "Description": "Basic Authorization header using the username and password.",
+        "Scheme": "basic",
+        "In": "Header",
+        "Requirement": {
+          "Scheme": {
+            "Reference": { "Id": "basic", "Type": "SecurityScheme" },
+            "Accesses": []
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### 6.5.13 在线测试
+
+Swagger 内置了在线测试功能，可直接在文档界面中测试接口。
+
+### 6.5.14 性能监视 MiniProfiler
+
+> **功能移除声明**：以下内容在 Furion 4.9.7.75+ 版本中已移除。
+
+规范化文档默认集成了 MiniProfiler 第三方性能组件，通过该组件可以方便查看请求性能、异常堆栈、数据库操作等信息。
+
+> 也可以通过 `appsettings.json` 中 `AppSettings:InjectMiniProfiler` 设为 `false` 关闭。
+
+### 6.5.15 定义接口输出类型
+
+```csharp
+using Furion.DynamicApiController;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Furion.Application
+{
+    public class FurionAppService : IDynamicApiController
+    {
+        [ProducesResponseType(201, Type = typeof(TestDto))]
+        [ProducesResponseType(400)]
+        public string Get()
+        {
+            return nameof(Furion);
+        }
+    }
+}
+```
+
+### 6.5.16 隐藏特定分组
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "GroupOpenApiInfos": [
+      {
+        "Group": "Group1",
+        "Visible": false
+      }
+    ]
+  }
+}
+```
+
+### 6.5.17 中文乱码问题
+
+默认情况下 `.json` 文件并未采用 `utf-8` 编码，所以如果配置中文分组信息就会出现乱码情况，这时候只需要修改 `.json` 文件编码为 `utf-8` 即可。
+
+### 6.5.18 生产环境中关闭 Swagger
+
+```json
+{
+  "AppSettings": {
+    "InjectSpecificationDocument": false
+  }
+}
+```
+
+### 6.5.19 设置 Example Value 默认值
+
+Swagger 会自动根据对象类型输入参数添加 Example Value 默认值，如果我们需要自定义这些默认值，只需要添加 `/// <example>默认值</example>` 注释即可。
+
+**属性默认值：**
+
+```csharp
+/// <summary>
+/// 年龄
+/// </summary>
+/// <example>13</example>
+[Required, Range(10, 110)]
+public int Age { get; set; }
+```
+
+**参数默认值：**
+
+```csharp
+/// <summary>
+/// 提交
+/// </summary>
+/// <param name="id" example="1">用户 Id</param>
+public void PostId(int id)
+{
+}
+```
+
+更多类型默认值设置示例：
+
+| 类型 | 示例 |
+|------|------|
+| bool | `/// <example>true</example>` |
+| string | `/// <example>foobar</example>` |
+| number | `/// <example>123</example>` |
+| null | `/// <example>null</example>` |
+| array | `/// <example>[ 1, 2, 3 ]</example>` |
+| 空数组 | `/// <example>&quot;[]&quot;</example>` |
+| 空对象 | `/// <example>&quot;{}&quot;</example>` |
+
+> **关于 object 类型输入参数**：默认情况下，Example Value 不会显示 object 类型的对象属性。如果需要强制显示，只需要添加 `/// <example>"object"</example>` 注释即可。
+
+### 6.5.20 自定义 Swagger 配置
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddInject(options =>
+    {
+        options.ConfigureSwaggerGen(gen =>
+        {
+           // ....
+        });
+    });
+}
+
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    // Furion 4.4.8+ 版本可以 app.UseInject(options => {})
+    app.UseInject(configure: options =>
+    {
+        options.ConfigureSwagger(swg =>
+        {
+            // ....
+        });
+
+        options.ConfigureSwaggerUI(ui =>
+        {
+            // ....
+        });
+    });
+}
+```
+
+### 6.5.21 配置 Swagger 的 SchemaIds
+
+```csharp
+services.AddControllersWithViews()
+        .AddInject(options =>
+        {
+            options.ConfigureSwaggerGen(gen =>
+            {
+                gen.CustomSchemaIds(x => x.FullName);
+            });
+        });
+```
+
+### 6.5.22 自定义 swagger.json 路由模板
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "RouteTemplate": "myapp/{documentName}/xxxx.json"
+  }
+}
+```
+
+> `{documentName}` 会在运行时替换为分组名。
+
+### 6.5.23 关于 application/x-www-form-urlencoded 请求
+
+默认情况下，Swagger 并未添加 `application/x-www-form-urlencoded` 支持，如需启用：
+
+```csharp
+[Consumes("application/x-www-form-urlencoded")]
+public async Task<IActionResult> Test([FromForm] TestRequest testRequest)
+{
+    // ....
+}
+```
+
+> **特别注意**：参数必须贴 `[FromForm]` 特性。另外请求时将参数按 URL 地址拼接并放在 Body 中请求。
+
+### 6.5.24 Swagger 出现 CORS 问题解决
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "HideServers": true
+  }
+}
+```
+
+### 6.5.25 Swagger 出现默认 text/xml/text/plain 参数问题解决
+
+产生此原因有两个必要条件：使用了 `Microsoft.AspNetCore.Mvc.NewtonsoftJson` 包并添加了 `AddNewtonsoftJson()` 注册，且 `.AddNewtonsoftJson()` 写在了 `.AddInjectWithUnifyResult()` 后面。
+
+解决方法：先注册 `.AddNewtonsoftJson()` 再注册规范化结果：
+
+```csharp
+services.AddControllers()
+        .AddNewtonsoftJson()
+        .AddInjectWithUnifyResult();
+```
+
+如果配置上述代码之后出现 `application/json-patch+json` 默认在第一位：
+
+```csharp
+services.Configure<MvcOptions>(options =>
+{
+    options.InputFormatters.RemoveType(typeof(NewtonsoftJsonPatchInputFormatter));
+});
+```
+
+### 6.5.26 Swagger 多语言支持
+
+在 Furion 2.9.0+ 版本已经支持了 Swagger 文档地址 `?culture=en-US` 参数多语言转发功能，Swagger 地址带 `?culture=` 参数将自动添加到每一个请求的 api 地址中。
+
+### 6.5.27 自定义逻辑控制 Swagger 每一个 api 可见性
+
+```csharp
+services.AddInject(options =>
+{
+    options.ConfigureSwaggerGen(gen =>
+    {
+        gen.DocInclusionPredicate((currentGroup, apiDescription) =>
+        {
+            // Furion 内部检查，必须放第一行
+            var isShow = SpecificationDocumentBuilder.CheckApiDescriptionInCurrentGroup(currentGroup, apiDescription);
+
+            // 获取当前方法
+            _ = apiDescription.TryGetMethodInfo(out var method);
+
+            // 有了方法，这里做你想做的事情，isShow 设置 true 可见，设置 false 不可见
+
+            return isShow;
+        });
+    });
+});
+```
+
+### 6.5.28 配置 MVC 控制器支持规范化处理
+
+```json
+{
+  "UnifyResultSettings": {
+    "SupportMvcController": true
+  }
+}
+```
+
+### 6.5.29 Swagger 刷新记住授权状态
+
+默认情况下，Swagger 刷新浏览器后授权状态将被重置。通过下面代码在**用户登录成功后**调用即可：
+
+```csharp
+_httpContextAccessor.HttpContext.SigninToSwagger("传入 token");
+```
+
+### 6.5.30 带登录的 Swagger 文档
+
+> **版本说明**：仅限 Furion v3.3.3+ 版本使用。
+
+默认情况下，Swagger 是任何人都可以访问的，通过配置 `LoginInfo` 可以添加登录功能：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "LoginInfo": {
+      "Enabled": true,
+      "CheckUrl": "/Home/CheckUrl",
+      "SubmitUrl": "/Home/SubmitUrl",
+      "UserName": "admin",
+      "Password": "admin",
+      "EnableOnProduction": false,
+      "DefaultUsername": "admin",
+      "DefaultPassword": "admin"
+    }
+  }
+}
+```
+
+配置说明：
+
+| 字段 | 说明 |
+|------|------|
+| `Enabled` | 是否启用登录授权，默认 false |
+| `CheckUrl` | 检查登录状态的 Url 地址，POST 请求，已授权返回 200，否则返回 401 |
+| `SubmitUrl` | 提交登录的 Url 地址，POST 请求且只有一个 `SpecificationAuth` 类型参数 |
+| `EnableOnProduction` | 是否设置生产环境自动开启（4.9.5.7+） |
+| `DefaultUsername` | 默认用户名（4.9.7.113+） |
+| `DefaultPassword` | 默认密码（4.9.7.113+） |
+
+#### Controller（MVC）方式
+
+```csharp
+using Furion.SpecificationDocument;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Furion.Web.Entry.Controllers;
+
+public class HomeController : Controller
+{
+    [HttpPost, AllowAnonymous, NonUnify]
+    public int CheckUrl()
+    {
+        return 401;
+    }
+
+    [HttpPost, AllowAnonymous, NonUnify]
+    public int SubmitUrl([FromForm] SpecificationAuth auth)
+    {
+        var userName = App.Configuration["SpecificationDocumentSettings:LoginInfo:UserName"];
+        var password = App.Configuration["SpecificationDocumentSettings:LoginInfo:Password"];
+
+        if (auth.UserName == userName && auth.Password == password)
+        {
+            return 200;
+        }
+        else
+        {
+            return 401;
+        }
+    }
+}
+```
+
+#### WebAPI/动态API 方式
+
+```csharp
+using Furion.SpecificationDocument;
+
+namespace MyProject.Application;
+
+public class SwaggerLoginServices : IDynamicApiController
+{
+    [HttpPost, AllowAnonymous, NonUnify]
+    public int CheckUrl()
+    {
+        return 401;
+    }
+
+    [HttpPost, AllowAnonymous, NonUnify]
+    public int SubmitUrl([FromForm] SpecificationAuth auth)
+    {
+        var userName = App.Configuration["SpecificationDocumentSettings:LoginInfo:UserName"];
+        var password = App.Configuration["SpecificationDocumentSettings:LoginInfo:Password"];
+
+        if (auth.UserName == userName && auth.Password == password)
+        {
+            return 200;
+        }
+        else
+        {
+            return 401;
+        }
+    }
+}
+```
+
+### 6.5.31 inheritdoc 实现注释继承
+
+> **版本说明**：仅限 Furion v3.3.3+ 版本使用。
+
+```csharp
+using Furion.DynamicApiController;
+
+namespace Furion.Application
+{
+    /// <inheritdoc cref="ITestInheritdoc" />
+    public class TestInheritdoc : ITestInheritdoc, IDynamicApiController
+    {
+        /// <inheritdoc cref="ITestInheritdoc.GetName"/>
+        public string GetName()
+        {
+            return "Furion";
+        }
+
+        /// <inheritdoc />
+        public string GetVersion()
+        {
+            return "3.3.3";
+        }
+    }
+
+    /// <summary>
+    /// 测试注释继承
+    /// </summary>
+    public interface ITestInheritdoc
+    {
+        /// <summary>
+        /// 获取名称
+        /// </summary>
+        string GetName();
+
+        /// <summary>
+        /// 获取版本
+        /// </summary>
+        string GetVersion();
+    }
+}
+```
+
+> **注意事项**：`<inheritdoc />` 不指定 `cref` 仅限成员可用且所在的类型必须指定 `<inheritdoc cref="" />`，这样才能自动识别。
+
+### 6.5.32 启用 All Groups 分组功能
+
+> **版本说明**：仅限 Furion v3.3.4+ 版本使用。
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "EnableAllGroups": true
+  }
+}
+```
+
+### 6.5.33 接口过时控制
+
+> **版本说明**：仅限 Furion v3.3.5+ 版本使用。
+
+只需要在方法上面贴 `[Obsolete]` 即可：
+
+```csharp
+[Obsolete("GetName() 已经过时，请调用 GetFrameworkName() 替代")]
+public string GetName()
+{
+    return nameof(Furion);
+}
+```
+
+### 6.5.34 单一接口更多描述
+
+> **版本说明**：仅限 Furion v3.3.5+ 版本使用。
+
+```csharp
+[ApiDescriptionSettings(Description = "我是一段描述，显示更多内容 <button>我是按钮</button>")]
+public string add()
+{
+    //....
+}
+```
+
+### 6.5.35 Swagger 异常/不能显示/错误处理
+
+有时候可能因为错误的配置导致 Swagger 不能显示，这时候只需要复制提示的错误 `.json` 链接地址到浏览器中访问即可：
+
+```
+https://localhost:你的端口/swagger/Default/swagger.json
+```
+
+这样就可以看到详细的错误了。
+
+### 6.5.36 自定义 Swagger 的 SchemaId
+
+> **版本说明**：仅限 Furion v3.6.4+ 版本使用。
+
+```csharp
+using Furion.SpecificationDocument;
+
+[SchemaId("Other_")]
+public class PersonDto
+{
+    // ...
+}
+```
+
+`SchemaIdAttribute` 配置选项：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `SchemaId` | string | 自定义 SchemaId，只能是字母、数字、下划线组合 |
+| `Replace` | bool | 是否完全替换，默认 false（默认是作为前缀拼接） |
+
+### 6.5.37 自定义 Swagger 的 OperationId
+
+> **版本说明**：仅限 Furion 4.1.7+ 版本使用。
+
+```csharp
+using Furion.SpecificationDocument;
+
+public class PersonDto
+{
+    [OperationId("MyClientMethodName")]
+    public string TestMethod()
+    {
+        // ...
+    }
+}
+```
+
+### 6.5.38 Swagger 接口文档支持完整的 Markdown
+
+在 Furion 最新版中，支持了完整的 Markdown 注释，通过 `/// <remarks>` 标签编写 Markdown 内容即可在 Swagger 中渲染。
+
+### 6.5.39 第三方 UI 集成，如 Knife4jUI
+
+在 `YourPoject.Web.Core` 层安装 `IGeekFan.AspNetCore.Knife4jUI` 即可。
+
+**Knife4jUI 独立版本配置：**
+
+```csharp
+var routePrefix = "api";
+
+app.UseKnife4UI(options =>
+{
+    options.RoutePrefix = routePrefix;
+    foreach (var groupInfo in SpecificationDocumentBuilder.GetOpenApiGroups())
+    {
+        options.SwaggerEndpoint("/" + groupInfo.RouteTemplate, groupInfo.Title);
+    }
+});
+
+app.UseInject(routePrefix);
+```
+
+**Knife4jUI 和 Swagger 共存版本配置：**
+
+```csharp
+app.UseKnife4UI(options =>
+{
+    options.RoutePrefix = "newapi";
+    foreach (var groupInfo in SpecificationDocumentBuilder.GetOpenApiGroups())
+    {
+        options.SwaggerEndpoint("/" + groupInfo.RouteTemplate, groupInfo.Title);
+    }
+});
+
+app.UseInject(); // Furion 默认 api 地址为 /api
+```
+
+如需实现登录之后自动将 token 添加到头部可在登录接口 `AfterScript` 执行：
+
+```javascript
+ke.global.setAllHeader(
+  "Authorization",
+  "Bearer " + ke.response.headers["access-token"],
+);
+```
+
+### 6.5.40 添加 Swagger 请求响应拦截
+
+```csharp
+app.UseInject(options =>
+{
+    options.ConfigureSwaggerUI(ui =>
+    {
+        // 请求拦截
+        ui.UseRequestInterceptor("function(request) { return defaultRequestInterceptor(request); }");
+        // 响应拦截
+        ui.UseResponseInterceptor("function(response) { return defaultResponseInterceptor(response); }");
+    });
+});
+```
+
+> **注意**：`UseRequestInterceptor` 和 `UseResponseInterceptor` 代码**不能换行**且须在 `defaultRequestInterceptor(request)` 和 `defaultResponseInterceptor(response)` 之前编写自定义代码。
+
+添加自定义 header 示例：
+
+```csharp
+app.UseInject(options =>
+{
+    options.ConfigureSwaggerUI(ui =>
+    {
+        // 注意代码不能换行！
+        ui.UseRequestInterceptor("function(request) { request.headers['framework']='Furion'; return defaultRequestInterceptor(request); }");
+    });
+});
+```
+
+### 6.5.41 枚举类型值
+
+> **版本说明**：仅限 Furion 4.8.8.35+ 版本使用。
+
+默认情况下枚举类型值会生成字符串类型，如需生成值类型则添加 `[EnumToNumber]` 特性。如果枚举项存在中文，会强制生成为值类型。
+
+```csharp
+[EnumToNumber]
+public enum NoticeTypeEnum
+{
+    NOTICE = 1,
+    ANNOUNCEMENT = 2,
+}
+```
+
+也支持全局配置：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "EnumToNumber": true
+  }
+}
+```
+
+### 6.5.42 运行时修改 Swagger UI 信息
+
+通过依赖注入 `ISwaggerProvider` 接口操作：
+
+```csharp
+var openApiInfos = SpecificationDocumentBuilder.GetOpenApiGroups();
+var openApiDocument = _swaggerProvider.GetSwagger("Default");
+
+openApiDocument.Info.Title = "我是新标题";
+openApiDocument.Info.Description = "我是新描述";
+```
+
+### 6.5.43 隐藏特定控制器或 Action
+
+```csharp
+[ApiDescriptionSettings(false)]
+public void IgnoreSomeMethod()
+{
+}
+
+// Furion 4.9.3.1+ 支持
+[SwaggerIgnore] // 支持类、方法、函数、参数、属性
+public void IgnoreSomeMethod()
+{
+}
+```
+
+> 如果不希望生成路由，那么可贴 `[NonAction]` 特性或者选择非 `public` 修饰即可。
+
+### 6.5.44 二级虚拟目录/Yarp/Nginx 代理问题
+
+> **版本说明**：仅限 Furion 4.9.3.1+ 版本使用。
+
+```csharp
+// 多种配置方式，取其一即可
+app.UseInject(withProxy: true);
+app.UseInject(string.Empty, withProxy: true);
+app.UseInject("api", withProxy: true);
+app.UseInject("api/abc", withProxy: true);
+```
+
+### 6.5.45 控制 Schema 展开深度
+
+```csharp
+app.UseInject(options =>
+{
+    options.ConfigureSwaggerUI(ui =>
+    {
+        ui.DefaultModelExpandDepth(5);
+    });
+});
+```
+
+### 6.5.46 第三方 UI 集成，如 Scalar
+
+在 `YourPoject.Web.Core` 层安装 `Scalar.AspNetCore` 即可。
+
+```csharp
+app.UseInject();
+
+app.UseEndpoints(endpoints =>
+{
+    endpoints.MapScalarApiReference(options =>
+    {
+        foreach (var groupInfo in SpecificationDocumentBuilder.GetOpenApiGroups())
+        {
+            options.AddDocument(groupInfo.Group, groupInfo.Title, groupInfo.RouteTemplate);
+        }
+    });
+});
+```
+
+之后打开浏览器访问 `/scalar` 即可。
+
+还可以通过 `HttpContext` 判断实现授权登录：
+
+```csharp
+endpoints.MapScalarApiReference("myapi", (options, httpContext) =>
+{
+    foreach (var groupInfo in SpecificationDocumentBuilder.GetOpenApiGroups())
+    {
+        options.AddDocument(groupInfo.Group, groupInfo.Title, groupInfo.RouteTemplate);
+    }
+});
+```
+
+---
+
+## 6.6 SpecificationDocumentSettings 配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `DocumentTitle` | string | `Specification Api Document` | 文档标题 |
+| `DefaultGroupName` | string | `Default` | 默认分组名 |
+| `EnableAuthorized` | bool | `true` | 是否启用权限控制 |
+| `LatestVersion` | bool | `false` | 采用最新 Swagger 版本（4.9.7.205+） |
+| `RoutePrefix` | string | `api` | 规范化文档地址，设空字符串则为首页 |
+| `DocExpansionState` | DocExpansion | `List` | 文档显示方式：List / Full / None |
+| `XmlComments` | string | 三个默认程序集 | 程序集注释描述文件名 |
+| `GroupOpenApiInfos` | SpecificationOpenApiInfo[] | `{ 'Group': 'Default'}` | 分组信息配置 |
+| `SecurityDefinitions` | SpecificationOpenApiSecurityScheme[] | `[]` | 安全策略定义配置 |
+| `Servers` | OpenApiServer[] | `[]` | 配置 Server 下拉列表 |
+| `HideServers` | bool | `true` | 是否隐藏 Server 下拉列表 |
+| `RouteTemplate` | string | `swagger/{documentName}/swagger.json` | 文档路由模板 |
+| `PackagesGroups` | string[] | `[]` | 模块化内置分组名称 |
+| `EnableEnumSchemaFilter` | bool | `true` | 启用枚举 Schema 筛选器 |
+| `EnableTagsOrderDocumentFilter` | bool | `true` | 启用标签排序筛选器 |
+| `ServerDir` | string | 空 | IIS Application 部署名（v3.2.0+） |
+| `LoginInfo` | SpecificationLoginInfo | `null` | 登录配置（v3.3.3+） |
+| `EnableAllGroups` | bool | `false` | 启用总分组功能（v3.3.4+） |
+| `EnumToNumber` | bool | `false` | 枚举生成值类型（4.8.8.35+） |
+| `EnableXmlComments` | bool | `true` | 是否自动加载 Xml 注释（4.9.3.1+） |
+
+`SpecificationOpenApiInfo` 内置配置：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `Group` | string | 分组唯一标识，必填 |
+| `Order` | int | 分组排序，数字越大排前面，默认 0 |
+| `Visible` | bool | 配置分组是否可见，默认 true |
+| `Title` | string | 配置分组标题 |
+| `Description` | string | 配置分组描述 |
+| `Version` | string | 配置分组版本，默认 1.0 |
+| `TermsOfService` | Uri | 配置相关链接地址 |
+| `Contact` | OpenApiContact | 配置联系方式 |
+| `License` | OpenApiLicense | 配置协议 |
+
+---
+
+## 6.7 统一返回值模型/规范化结果/API 返回值
+
+Furion 框架提供规范化结果功能，可以通过实现 `IUnifyResultProvider` 提供器实现统一规范化返回值定制。
+
+### 定义结果包装类型
+
+```csharp
+// 必须是泛型类型
+public class YourRESTfulResult<T>
+{
+    /// <summary>
+    /// 状态码
+    /// </summary>
+    public int? StatusCode { get; set; }
+
+    /// <summary>
+    /// 数据
+    /// </summary>
+    public T Data { get; set; }
+
+    /// <summary>
+    /// 执行成功
+    /// </summary>
+    public bool Succeeded { get; set; }
+
+    /// <summary>
+    /// 错误信息
+    /// </summary>
+    public object Errors { get; set; }
+
+    /// <summary>
+    /// 附加数据
+    /// </summary>
+    public object Extras { get; set; }
+
+    /// <summary>
+    /// 时间戳
+    /// </summary>
+    public long Timestamp { get; set; }
+}
+```
+
+### 定义 IUnifyResultProvider 实现类
+
+贴特性 `[UnifyModel(typeof(YourRESTfulResult<>))]`：
+
+```csharp
+using Furion.DataValidation;
+using Furion.UnifyResult.Internal;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+using System;
+using System.Threading.Tasks;
+
+namespace YourProject.UnifyResult
+{
+    [UnifyModel(typeof(YourRESTfulResult<>))]
+    public class YourRESTfulResultProvider : IUnifyResultProvider
+    {
+        public IActionResult OnAuthorizeException(DefaultHttpContext context, ExceptionMetadata metadata)
+        {
+            return new JsonResult(YourRESTfulResult(metadata.StatusCode, data: metadata.Data, errors: metadata.Errors)
+                , UnifyContext.GetSerializerSettings(context));
+        }
+
+        public IActionResult OnException(ExceptionContext context, ExceptionMetadata metadata)
+        {
+            return new JsonResult(YourRESTfulResult(metadata.StatusCode, data: metadata.Data, errors: metadata.Errors)
+                , UnifyContext.GetSerializerSettings(context));
+        }
+
+        public IActionResult OnSucceeded(ActionExecutedContext context, object data)
+        {
+            return new JsonResult(YourRESTfulResult(StatusCodes.Status200OK, true, data)
+                , UnifyContext.GetSerializerSettings(context));
+        }
+
+        public IActionResult OnValidateFailed(ActionExecutingContext context, ValidationMetadata metadata)
+        {
+            return new JsonResult(YourRESTfulResult(metadata.StatusCode ?? StatusCodes.Status400BadRequest, data: metadata.Data, errors: metadata.ValidationResult)
+                , UnifyContext.GetSerializerSettings(context));
+        }
+
+        public async Task OnResponseStatusCodes(HttpContext context, int statusCode, UnifyResultSettingsOptions unifyResultSettings)
+        {
+            UnifyContext.SetResponseStatusCodes(context, statusCode, unifyResultSettings);
+
+            switch (statusCode)
+            {
+                case StatusCodes.Status401Unauthorized:
+                    await context.Response.WriteAsJsonAsync(YourRESTfulResult(statusCode, errors: "401 Unauthorized")
+                        , App.GetOptions<JsonOptions>()?.JsonSerializerOptions);
+                    break;
+                case StatusCodes.Status403Forbidden:
+                    await context.Response.WriteAsJsonAsync(YourRESTfulResult(statusCode, errors: "403 Forbidden")
+                        , App.GetOptions<JsonOptions>()?.JsonSerializerOptions);
+                    break;
+                default: break;
+            }
+        }
+
+        private static YourRESTfulResult<object> YourRESTfulResult(int statusCode, bool succeeded = default, object data = default, object errors = default)
+        {
+            return new YourRESTfulResult<object>
+            {
+                StatusCode = statusCode,
+                Succeeded = succeeded,
+                Data = data,
+                Errors = errors,
+                Extras = UnifyContext.Take(),
+                Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
+            };
+        }
+    }
+}
+```
+
+### 注册
+
+```csharp
+services.AddControllers()
+        .AddInjectWithUnifyResult<YourRESTfulResultProvider>();
+```
+
+> **特别注意**：默认情况下，规范化结果不会对 401、403、404 状态码进行规范化处理，如需启用：
+
+```csharp
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    // 添加规范化结果状态码，需要在这里注册
+    app.UseUnifyResultStatusCodes();
+    // 如果和域登录冲突可设置参数 withAuthorizationHeaderCheck: false
+}
+```
+
+### 6.7.1 排除规范化处理
+
+贴 `[NonUnify]` 特性即可。
+
+如果接口没有返回值（`void`/`Task`），也会被排除规范化处理。如果希望此类接口支持规范化处理，可在方法或所在的类型上添加 `[ForceUnify]` 特性。
+
+### 6.7.2 规范化结果添加额外数据
+
+```csharp
+UnifyContext.Fill(new { Message = "操作成功" });
+```
+
+### 6.7.3 自定义特别接口规范化结果
+
+```csharp
+[UnifyResult(typeof(Person))]
+public Person GetPerson(int id)
+{
+    // ...
+}
+```
+
+---
+
+## 6.8 支持多套规范化配置
+
+> **版本说明**：仅限 Furion 4.4.4+ 版本使用。
+
+### 定义规范化处理提供程序
+
+```csharp
+[UnifyModel(typeof(MyResult<>))]
+public class SpeciallyResultProvider : IUnifyResultProvider
+{
+    // 参考 6.7 节的规范化处理写法实现各方法
+}
+
+public class MyResult<T>
+{
+    public T Data { get; set; }
+}
+```
+
+### 注册
+
+```csharp
+services.AddUnifyProvider<SpeciallyResultProvider>("specially");
+// 指定规范化唯一名称，如果不指定就会替代默认的
+```
+
+### 在控制器/动态 WebAPI 中使用
+
+```csharp
+public class TestUnifyProvider : IDynamicApiController
+{
+    public string DefaultUnify()
+    {
+        return "test";
+    }
+
+    [UnifyProvider]
+    public string DefaultUnify2()
+    {
+        return "test";
+    }
+
+    [UnifyProvider("specially")]
+    public string SpeciallyUnify()
+    {
+        return "特别";
+    }
+}
+```
+
+---
+
+## 6.9 针对特定控制器或特定方法配置序列化选项
+
+### 6.9.1 通过 JsonResult 设置第二个参数
+
+```csharp
+[NonUnify]
+public IActionResult SpecialApi()
+{
+    return new JsonResult(new YourRESTfulResult<object>
+    {
+        StatusCode = 200,
+        Succeeded = true,
+        Data = new { Name = "Furion" },
+        Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
+    }, new JsonSerializerOptions
+    {
+        PropertyNamingPolicy = null
+    });
+}
+```
+
+### 6.9.2 注册多套序列化配置选项（推荐）
+
+> **版本说明**：仅限 Furion 4.6.6+ 版本使用。
+
+```csharp
+services.AddUnifyJsonOptions("special", new JsonSerializerOptions
+{
+    PropertyNamingPolicy = null
+});
+```
+
+使用方式：
+
+```csharp
+[UnifySerializerSetting("special")]
+public object SpecialApi()
+{
+    return new { Name = "Furion" };
+}
+```
+
+也可以手动返回 `IActionResult`（Furion 4.8.7.1+）：
+
+```csharp
+public IActionResult SpecialApi()
+{
+    return new JsonResult(new { Name = "Furion" }, UnifyContext.GetSerializerSettings("special"));
+}
+```
+
+> **特别提醒**：目前 Swagger 暂未提供个别的接口自定义 schema 序列化选项。