Asp.Net Core Api使用Swagger管理文档教程的安装

公司使用Core下的Swagger,本文章作为笔记
Core下的Swagger和传统framework Mvc下的Swagger是不一样的,两者的差距:

其一:引用的程序集不一样。

其二:安装完程序集后需要配置的地方不一样,

ramework 下的Swagger安装完后会有swaggerconfig和swaggernet这连个文件。它也是在这两个文件下做配置。

Core 的安装完成以后没有这两个文件,它的配置是在Core项目里Startup文件里做配置!

---对你的Api项目找到NuGet管理包,然后搜索“Swashbuckle.AspNetCore”。找到下面图片中的程序包然后安装

Swashbuckle.AspNetCore

---接下来就是配置的问题了,在Startup.cs文件中做配置
1.首先先引入如下命名空间:

using Swashbuckle.AspNetCore.Swagger;

2.将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:

 //注册Swagger生成器,定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "v1", Version = "接口文档" });

                // 下面三个方法为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
                var xmlPath = Path.Combine(basePath, "Zhou3.xml");
                c.IncludeXmlComments(xmlPath);

            });

3.在 Startup.Configure 方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务:

 // 配置Swagger  必须加在app.UseMvc前面
            app.UseSwagger();
            //Swagger Core需要配置的  必须加在app.UseMvc前面
            app.UseSwaggerUI(c =>
            {
                  
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "my api");
            });

4.启用XML 注释:
右键单击“解决方案资源管理器”中的项目,然后选择“属性”
查看“生成”选项卡的“输出”部分下的“XML 文档文件”框输入生成位置
5.启动项更改在PropertieslaunchSettings.json文件中 "launchUrl": "swagger"

ASP.NET Core 在 Swagger UI 中显示自定义的 Header Token

1创建一个过滤器类 AuthTokenHeaderParameter

 public class AuthTokenHeaderParameter : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            operation.Parameters = operation.Parameters ?? new List<IParameter>();
            //MemberAuthorizeAttribute 自定义的身份验证特性标记
            var isAuthor = operation != null && context != null;
            if (isAuthor)
            {
                //in query header 
                operation.Parameters.Add(new NonBodyParameter()
                {
                    Name = "Token",
                    In = "header", //query formData ..
                    Description = "身份验证",
                    Required = false,
                    Type = "string"
                });
            }
        }
    }

2然后在配置 Swagger 的地方,ConfigureServices.cs做一些修改:

c.OperationFilter<AuthTokenHeaderParameter>();
注意:

​ 1.对于 Linux 或非 Windows 操作系统,文件名和路径区分大小写。 例如,“SwaggerDemo.xml”文件在 Windows 上有效,但在 CentOS 上无效。

​ 2.获取应用程序路径,建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

3.要想有注释需要添加的代码在下面的代码的注释里有,就是最下面的三个代码。第二行的XML文件名注意对应你自己项目的XML文件名!

Last modification:January 14th, 2020 at 01:15 pm
如果觉得我的文章对你有用,请随意赞赏