Skip to main content

7. 规范化文档配置

配置智能提示和校验

如需编写配置的时候提供智能提示和校验,可查看 【2.7 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 已弃用
    • RoutePrefix:规范化文档地址,string,默认 api如果希望在首页,改为空字符串即可
    • DocExpansionState:文档显示方式,DocExpansion,默认 List,取值:
      • List:列表式(展开子类),默认值
      • Full:完全展开
      • None:列表式(不展开子类)
    • XmlComments:程序集注释描述文件名(可带 .xmlstring,默认 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 请求
    • SubmitUrl:提交登录的 Url 地址,该地址必须是 POST 请求且只有一个 SpecificationAuth 类型参数,成功登录返回 200,否则返回 401,支持相对地址,以 / 开头
    • EnableAllGroups:启用 Swagger 总分组功能,自动将所有分组的接口合并到 All Groups 中,bool 类型,默认 false仅在 Furion v3.3.4+` 有效

另外 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.icu",
"Contact": {
"Name": "百小僧",
"Url": "https://gitee.com/monksoul",
"Email": "monksoul@outlook.com"
},
"License": {
"Name": "MIT",
"Url": "https://gitee.com/dotnetchina/Furion/blob/alpha/LICENSE"
}
}
]
}
}