.net5 - 创建Web.Api项目（二）Swagger配置

 Swagger基础配置

1、非生产环境，不开启Swagger，根据实际需要决定

2、设置项目属性

　　xml文件地址：当前地址【Test.WebApi.xml】，其他项目地址【..\Test.WebApi\Test.WebApi.xml】

3、修改服务注册、注意修改xml文件名称

        public Startup(IConfiguration configuration, IHostEnvironment env)
        {
            Configuration = configuration;
            Env = env;
        }

        public IHostEnvironment Env { get; }

        private readonly string apiName = "基础用户信息服务";

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",//版本号
                    Title = $"{apiName} 接口文档——dotnetcore 5.0",//编辑标题
                    Description = $"{apiName} HTTP API V1",//编辑描述
                    //Contact = new OpenApiContact { Name = apiName, Email = "[e-mail]" },//编辑联系方式
                    License = new OpenApiLicense { Name = apiName }//编辑许可证
                });
                c.OrderActionsBy(o => o.RelativePath);

                var xmlPath = Path.Combine(Env.ContentRootPath, "Test.WebApi.xml");// linux区分大小写
                c.IncludeXmlComments(xmlPath, true); // 把接口文档的路径配置进去。第二个参数表示的是是否开启包含对Controller的注释容纳【第二个参数可以不加】
            });
            #endregion

 

 Swagger设置参数（折叠、不显示Models【Schemas】）

                    c.DocExpansion(DocExpansion.None);//DocExpansion设置为none可折叠所有方法
                    c.DefaultModelsExpandDepth(-1);//DefaultModelsExpandDepth设置为-1 可不显示models【Schemas】

　　

 Swagger控制器的注释与排序

WebApi项目下新建【Swagger】文件夹，新建【AuthTagDescriptions】并继承【IDocumentFilter】

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;

namespace Test.WebApi.Swagger
{
    public class AuthTagDescriptions : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            swaggerDoc.Tags = new List<OpenApiTag>
            {
                new OpenApiTag{ Name = "OrgUnit", Description = "组织单元" },
                new OpenApiTag{ Name = "Employee", Description = "职员维护" },
                new OpenApiTag{ Name = "WeatherForecast", Description = "天气预报" }
            };
        }
    }
}

 在StartUp类中注入类：

                c.DocumentFilter<AuthTagDescriptions>();// 注入【注释/排序】文档

　　

 Swagger版本控制

添加枚举类（这个不是必须的）：

namespace Test.WebApi.Swagger
{
    /// <summary>
    /// Swagger版本枚举
    /// </summary>
    public enum ApiVersion
    {
        /// <summary>
        /// v1版本
        /// </summary>
        V1 = 1,
        /// <summary>
        /// v2版本
        /// </summary>
        V2 = 2
    }
}

2、StartUp注册服务：

                //版本控制
                typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                {
                    c.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Version = version,
                        Title = $"webapi {version}",
                        Description = $"Asp.NetCore Web API {version}"
                    });
                });

 3、启用Swagger

                    typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                    {
                        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);
                    });

  4、在控制器中使用ApiExplorerSettings标记：

    [ApiExplorerSettings(GroupName = "V2")]

 5、注意事项：

(1) 在控制器中使用ApiExplorerSettings标记时，GroupName的值要和ApiVersion中的枚举名称一致，否则Swagger列出的API版本列表不会有该控制器的API，导致Swagger网页中该控制器API文档不会出现。

(2) 枚举类型ApiVersion不是必须的，只是用它来获取版本列表，例如可以使用new List<string>() { "V1", "V2" }.ForEach代替typeof(ApiVersion).GetEnumNames().ToList().ForEach。