RuoVea.ExSwagger 10.0.0

RuoVea.ExSwagger

介绍

Swagger拓展插件 只需要添加该插件便可轻松使用 Swagger 使用方式.支持简体中文、繁体中文、粤语、日语、法语、英语.

语言I18n获取：Language.I18n

services.AddSwaggerSetup();

app.UseSwaggerMiddle(builder.Environment);

1.快速入门

通过Nuget安装组件

Install-Package RuoVea.ExSwagger

2、使用示例

builder.Services.AddSwaggerSetup();

app.UseSwaggerMiddle(builder.Environment);

3、隐藏swagger接口特性标识

Hidden、HiddenAttribute

4、配置

4.1、配置文件

  "$schema": "https://gitee.com/starry123/ruovea-extend/blob/NetCore/NetCore/RuoVea.ExSwagger/RuoVea.ExSwagger/ExSwagger.json",

  "Swagger": {
    "ClientId": null,
    "UseKnife4jUI": true,
    "VirtualPath": null, /*配置UI地址（处理二级虚拟目录）路径配置，设置为空，表示直接访问该文件*/
    "DocExpansionState": 1, // 0 List、1 Full、3 None
    "IsMiniProfile": false, //是否启用 MiniProfile
    "WithProxy": false, //解决 Swagger 被代理问题
    "Title": "API 文档",
    "ApiUrl": null, /*api 地址*/
    "ContactName": "xxx公司",
    "ContactEmail": "ruovea@foxmail.com",
    "ContactUrl": null,
    "LicenseName": null,
    "LicenseUrl": null,
    "TermsOfService": "https://www.ruovea.com",
    "Description": "Api接口采用token+签名验证，在使用swagger测试接口时须先获取Token；api-version接口版本号，默认为1.0，可以不填写，其他版本必须填写。",

    "ApiVersions": [
      {
        "Title": "基础模块",
        "Version": "v0"
      },
      {
        "Title": "系统基础模块",
        "Version": "v1"
      }
    ],

    /* 文档开启登录查看 生产环境默认开启 */
    "LoginInfo": {
      "Enabled": false, // 是否开启Swagger登录
      "EnableOnProduction": false, // 是否生产环境开启Swagger登录
      "CheckUrl": "/api/swagger/checkUrl",
      "SubmitUrl": "/api/swagger/submitUrl"
    }
    //"Servers": [
    //  {
    //    "Url": "",
    //    "Description": ""
    //  }
    //]
  }

4.1.1、开启Swagger登录接口实现

/// <summary>
/// Swagger登录检查 🔖
/// </summary>
/// <returns></returns>
[AllowAnonymous]
[NonRestfulResult]
[HttpPost("/api/swagger/checkUrl")]
public int SwaggerCheckUrl()
{
    return 200;// _httpContextAccessor.HttpContext.User.Identity.IsAuthenticated ? 200 : 401;
}

/// <summary>
/// Swagger登录提交 🔖
/// </summary>
/// <param name="userName"></param>
/// <param name="password"></param>
/// <returns></returns>
[AllowAnonymous]
[NonRestfulResult]
[HttpPost("/api/swagger/submitUrl")]
public int SwaggerSubmitUrl([FromForm] string userName, [FromForm] string password)
{
    try
    {
        return 200;
    }
    catch (Exception)
    {
        return 401;
    }
}

4.2、配置模型

/// <summary>
/// Swagger 配置文件
/// </summary>
public class SwaggerConfig
{
    /// <summary>
    /// 
    /// </summary>
    public string ClientId { get; set; }
    /// <summary>
    /// 配置UI地址（处理二级虚拟目录）路径配置，设置为空，表示直接访问该文件
    /// </summary>
    public string VirtualPath { get; set; }

    /// <summary>
    /// 标题
    /// </summary>
    public string Title { get; set; }
    /// <summary>
    /// api 地址
    /// </summary>
    public string ApiUrl { get; set; }
    /// <summary>
    /// 描述
    /// </summary>
    public string ContactName { get; set; }
    /// <summary>
    /// 邮箱
    /// </summary>
    public string ContactEmail { get; set; }
    /// <summary>
    /// url地址
    /// </summary>
    public string ContactUrl { get; set; }
    /// <summary>
    /// 名称
    /// </summary>
    public string LicenseName { get; set; }
    /// <summary>
    /// url地址
    /// </summary>
    public string LicenseUrl { get; set; }
    /// <summary>
    /// 服务
    /// </summary>
    public string TermsOfService { get; set; }
    /// <summary>
    /// 描述
    /// </summary>
    public string Description { get; set; }
    /// <summary>
    /// 是否启用 MiniProfile
    /// </summary>
    public bool IsMiniProfile { get; set; } = false;
    /// <summary>
    /// 解决 Swagger 被代理问题
    /// </summary>
    public bool WithProxy { get; set; } = false;
    /// <summary>
    /// 版本号
    /// </summary>
    public List<DocVersions> ApiVersions { get; set; } = new List<DocVersions>();
    /// <summary>
    /// 
    /// </summary>
    public bool UseKnife4jUI { get; set; } = true;
    /// <summary>
    /// List、Full、None
    /// </summary>
    public Swashbuckle.AspNetCore.SwaggerUI.DocExpansion DocExpansionState { get; set; } =  Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List;

    /// <summary>
    /// 隐藏 Servers
    /// </summary>
    public bool HideServers { get; set; } = false;
    /// <summary>
    /// 配置 Servers
    /// </summary>
    public List<OpenApiServer> Servers { get; set; } = new List<OpenApiServer>();

    /// <summary>
    /// 
    /// </summary>
    public LoginInfo LoginInfo { get; set; }
}
 
/// <summary>
/// 登录处理
/// </summary>
public class LoginInfo
{
    /// <summary>
    /// 开启
    /// </summary>
    public bool Enabled { get; set; } = false;
    /// <summary>
    /// 生产环境开启
    /// </summary>
    public bool EnableOnProduction { get; set; } = true;
    /// <summary>
    /// 
    /// </summary>
    public string CheckUrl { get; set; }
    /// <summary>
    /// 
    /// </summary>
    public string SubmitUrl { get; set; }
}

/// <summary>
/// 版本号
/// </summary>
public class DocVersions
{
    /// <summary>
    /// 版本
    /// </summary>
    public String Version { get; set; }
    /// <summary>
    /// 名称
    /// </summary>
    public String Title { get; set; }
}