7. 规范化文档配置

📝 模块更新日志

新特性
- 新增 Swagger 规范化文档支持配置默认深色模式 DarkMode ^4.9.8.31 ^{⏱️2026.03.31} 32cb2d5
- 新增规范化 Swagger 是否自动加载 Xml 注释文件配置 EnableXmlComments ^4.9.3.1 ^{⏱️2024.05.10} d01bbaa

配置智能提示和校验

如需编写配置的时候提供智能提示和校验，可查看【2.15 JSON Schema 使用】

只需要在 .json 文件头部添加下列配置即可：

{
  "$schema": "https://gitee.com/dotnetchina/Furion/raw/v4/schemas/v4/furion-schema.json"
}

7.1 关于配置

规范化文档配置指的是 Furion 框架 Swagger 文档配置选项。

7.2 配置信息

SpecificationDocumentSettings：配置根节点
- DocumentTitle：文档标题，string，默认 Specification Api Document
- DefaultGroupName：默认分组名，string，默认 Default
- EnableAuthorized：是否启用权限控制，bool，默认 true
- FormatAsV2：采用 Swagger 2.0 版本，bool，默认 false 已弃用
- LatestVersion ：采用最新的 Swagger 版本，bool，默认 false，启用可能会导致生成错误的客户端代码。Furion 4.9.7.205+ 支持
- RoutePrefix：规范化文档地址，string，默认 api，如果希望在首页，改为空字符串即可。
- DocExpansionState：文档显示方式，DocExpansion，默认 List，取值：
  - List：列表式（展开子类），默认值
  - Full：完全展开
  - None：列表式（不展开子类）
- XmlComments：程序集注释描述文件名（可带 .xml，string，默认 Furion.Application, Furion.Web.Entry, Furion.Web.Core
- GroupOpenApiInfos：分组信息配置，SpecificationOpenApiInfo[]，默认 { 'Group': 'Default'}
- SecurityDefinitions：安全策略定义配置，SpecificationOpenApiSecurityScheme[]，默认 []
- Servers：配置 Server 下拉列表，OpenApiServer[] 类型，默认 []，如：{Servers:[ { Url:"地址", Description:"描述"} ]}
- HideServers：是否隐藏 Server 下拉列表，bool 类型，默认 true
- RouteTemplate：配置文档 swagger.json 路由模板，默认模板：swagger/{documentName}/swagger.json, {documentName} 代表分组名，必须保留原样
- PackagesGroups：配置模块化内置分组名称，string[] 类型，默认 []
- EnableEnumSchemaFilter：启用枚举 Schema 筛选器，bool 类型，默认 true
- EnableTagsOrderDocumentFilter：启用标签排序筛选器，bool 类型，默认 true
- ServerDir：配置 IIS 添加 Application 部署名，string 类型，默认空，仅在 Furion v3.2.0+ 有效
- LoginInfo：配置 Swagger 是否需要登录才能访问，SpecificationLoginInfo 类型，默认 null，仅在 Furion v3.3.3+ 有效
  - Enabled：是否启用登录授权，默认 false
  - CheckUrl：检查登录状态的 Url 地址，该地址必须是 POST 请求，已授权返回 200，否则返回 401
  - SubmitUrl：提交登录的 Url 地址，该地址必须是 POST 请求且只有一个 SpecificationAuth 类型参数，成功登录返回 200，否则返回 401，支持相对地址，以 / 开头
  - EnableOnProduction：是否设置生产环境自动开启，当 Enabled 为 false 时依然有效
  - DefaultUsername：默认用户名，Furion 4.9.7.113 版本支持
  - DefaultPassword：默认密码，Furion 4.9.7.113 版本支持
- EnableAllGroups：启用 Swagger 总分组功能，自动将所有分组的接口合并到 All Groups 中，bool 类型，默认 false，仅在 Furion v3.3.4+ 有效
- EnumToNumber：枚举类型生成值类型，bool 类型，默认 false，仅在 Furion 4.8.8.35+ 有效
- EnableXmlComments：是否自动加载 Xml 注释文件，bool 类型，默认 true，仅在 Furion 4.9.3.1+ 有效
- DarkMode：是否默认深色模式，bool 类型，默认 false，仅在 Furion 4.9.8.31+ 有效

另外 SpecificationOpenApiInfo 内置配置如下：

Group：分组唯一标识，string 类型，必填
Order：分组排序，int 类型，数字越大排前面，默认 0
Visible：配置分组是否可见，bool 类型，默认 true
Title：配置分组标题，string 类型
Description：配置分组描述，string 类型
Version：配置分组版本，默认 1.0
TermsOfService：配置相关链接地址，Uri 类型
Contact：配置联系方式，OpenApiContact 类型
License：配置协议，OpenApiLicense 类型

7.3 配置示例

{
  "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"
        }
      }
    ]
  }
}

7.1 关于配置​

7.2 配置信息​

7.3 配置示例​

7.1 关于配置

7.2 配置信息

7.3 配置示例