Asp.Net Core遇到Swagger(三)-Swashbuckle技巧b篇

一、前言

接上篇Swashbuckle技巧a篇，本篇文章继续讲解基于Swashbuckle的实践应用操作和配置。此处为b篇

二、实践技巧

2.4 修改Swagger Json请求路径

1）默认路径

请求http://localhost:5000/swagger/v1/swagger.json，可查看到Swagger Json结构如下：

{
  "openapi": "3.0.1",
  "info": {
    "title": "swaggertestbase",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "http://localhost:5000"
    }
  ],
  "paths": {
    "/WeatherForecast": {
      "get": {
        "tags": [
          "WeatherForecast"
        ]
      }
    }
  }
}

2）自定义路径

自定义时，需要进行进行模板配置查看和依据实际需求机型节点配置，为Swagger中间件配置SwaggerOptions的RouteTemplate，对应的swagger-ui需要请求的Swagger Json地址也需要进行修改，

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
..........
    #region Swagger中间件相关
    //添加swagger配置，并启动中间件
    app.UseSwagger(options =>
        {
            options.RouteTemplate = "api-docs/{documentName}/swaggerapi.json";
        }
    );
    //启用Swagger-ui中间件，并配置swagger json的请求终节点
    app.UseSwaggerUI(options => {
        options.SwaggerEndpoint("/api-docs/v1/swaggerapi.json","ggcy docs");
    });
    #endregion
...........
}

Swagger Json访问地址变更为http://localhost:5000/api-docs/v1/swaggerapi.json内容不变

其中，RouteTemplate对应的值api-docs/{documentName}/swaggerapi.json，表示对应自定义的匹配路由，在启用SwaggerUI中间件时SwaggerEndpoint指定对应需要访问的Swagger Json，访问路径为/api-docs/v1/swaggerapi.json，其中v1为匹配到{documentName}，框架默认的文档名称为v1

2.5 修改文档swagger-ui访问前缀

1）修改前缀

默认情况下，访问Api文档，访问路径一般是xxxxx/swagger/index.html，前缀为swagger，需要自定义前缀时需要进行如下操作：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
..........
    #region Swagger中间件相关
    //添加swagger配置，并启动中间件
    app.UseSwagger(options =>
        {
            options.RouteTemplate = "{documentName}/swaggerapi.json";
        }
    );
    //启用Swagger-ui中间件，并配置swagger json的请求终节点
    app.UseSwaggerUI(options => {
        options.RoutePrefix = "api-docs";
        options.SwaggerEndpoint("/v1/swaggerapi.json","ggcy docs");
    });
    #endregion
...........
}

修改前缀的同时，也需要将Swagger中间件配置中RouteTemplate为{documentName}/swaggerapi.json，便于swagger-ui前端请求道对应带有前缀的swagger Json

2）运行效果

运行程序，访问地址http://localhost:5000/api-docs/index.html，出现如下结果

2.6 显示标签描述

1）加载xml注释文件

使用注释文件xml时，需要注意添加.xml文件引入时，注册服务时函数的参数值，

services.AddSwaggerGen(options =>
{
	...............
    //获取执行目录下的所有解释文件.xml
    Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "*.xml").ToList().ForEach(file =>
    {
        options.IncludeXmlComments(file,true);
    });
    ................
});

IncludeXmlComments参数解释如下：

//
// 摘要:
//     基于 XML 注释文件为操作、参数和模式注入人性化的描述 
//
// 参数:
//   swaggerGenOptions:
//
//   filePath:
//     包含 XML 注释的文件的绝对路径
//
//   includeControllerXmlComments:
//    用于指示是否应使用控制器 XML 注释（即摘要）的标志
//	  分配标签描述。 如果需要要自定义默认值，请不要设置此标志
//    通过 TagActionsBy 标记操作。 
public static void IncludeXmlComments(this SwaggerGenOptions swaggerGenOptions, string filePath, bool includeControllerXmlComments = false)
{
   swaggerGenOptions.IncludeXmlComments(() => new XPathDocument(filePath),includeControllerXmlComments);
}

2.7 按照约定生成Api分组

1）自定义约定

将控制器特定约定进行分组，以下为命名空间尾缀进行Api分组处理，

/// <summary>
/// 自定义ApiExplorGroup添加到控制器模型中
/// </summary>
public class ApiExplorerGroupVersionConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        string namespac = controller.ControllerType.Namespace;
        string groupname = namespac.Split(".").Last().ToLower();
        controller.ApiExplorer.GroupName = groupname;
    }
}

2）添加约束

Startup.cs中的服务注册函数中修改AddControllers函数配置，

public void ConfigureServices(IServiceCollection services)
{
    ..........
    //添加自定义apiexplor.groupname控制器模型属性
    services.AddControllers(configure => {
        configure.Conventions.Add(new ApiExplorerGroupVersionConvention());
    });
}

3）修改命名空间

修改控制器WeatherForecastController与ValuesController的命名空间分别为v1和v2，

//WeatherForecastController.cs
namespace swaggertestbase.Controllers.v1
{
    /// <summary>
    /// 天气预报服务
    /// </summary>
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        .......
    }
}

//ValuesController.cs
namespace swaggertestbase.Controllers.v2
{
    [ApiController]
    [Route("api/[controller]")]
    [ApiExplorerSettings(GroupName ="v2")]
    public class ValuesController : ControllerBase
    {
		.......
    }
}

运行效果中，会发现，切换到ggcy v2时，将不再包含天气预报相关控制器和api

2.8 自定义Action分组规则判定条件

1）引用依赖

Nuget引用Microsoft.AspNetCore.Mvc.Versioning 5.0.0

2）添加判定规则

修改服务注册中DocInclusionPredicate的ApiDescription.GroupName判定逻辑，实现依据version特性进行Api分组

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(
        options =>
        {
            ...........
            #region 自定义DocInclusionPredicate判定规则
            options.DocInclusionPredicate((docName, apiDesc) => {
                //判定当前执行是否为函数对象
                if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)) 
                    return false;
                //获取函数对应的自定义特性ApiVersionAttribute对应的版本集合
                var versions = methodInfo.GetCustomAttributes(true)
                .OfType<ApiVersionAttribute>()
                .SelectMany(x => x.Versions);
                //判定版本集合中是否与当前文档匹配
                return versions.Any(x => $"v{x}" == docName);
            });
            #endregion
        }
        );
			.........
}

3）添加案例控制器

创建Api控制器DocInclusionController，设定Version特性

namespace swaggertestbase.Controllers
{
    /// <summary>
    /// DocInclusion控制器
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class DocInclusionController : ControllerBase
    {
        /// <summary>
        /// 获取DocInclusion数据
        /// </summary>
        /// <returns>查询结果</returns>
        /// <remarks>
        /// GET: 
        ///     api/DocInclusionController
        /// </remarks>
        [HttpGet]
        [ApiVersion("1")]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }
}

运行效果：