.netCore3.0 + WebApi + Vue2.0项目搭建——（二）、Swagger的使用

一、什么是Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用：接口文档在线自动生成，功能测试

二、为什么使用Swagger

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

三、配置Swagger服务

1、引入Nuget包

利用NuGet包添加程序集应用

右键项目中的 依赖性-- > 管理NuGet程序包 --> 浏览

安装完成后即可在依赖性中查看到

2、配置服务

打开Startup.cs，编辑ConfigureServices方法

public string ApiName { get; set; } = "WebApi"; //定义成全局变量，方便修改

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //Swagger
            services.AddSwaggerGen(c => 
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = $"{ApiName} 接口文档-- .netCore3.0",
                    Description = $"{ApiName} 框架说明文档"

                });
                c.OrderActionsBy(o => o.RelativePath);
            });
        }

3、启动Http中间件

打开Startup.cs，编辑Configure方法

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseSwagger();

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"{ApiName} v1");

                // 路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,
                // 注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，
                // 如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "doc";
                c.RoutePrefix = "";
            });

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

4、查看效果

打开launchSettings.json文件，删除红色部分， launchUrl设置为空，或者删掉就行。

.net core 调试的两种方法有两种，IIS调试和项目自带的Kestrel web应用调式，这里从 launchsettings.json删除IIS调试使用Kestrel web就行

按F5调试查看结果

5、添加注释

右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：

这里我用的是相对路径，可以直接生成到 api 层的 bin文件夹下

如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：
打开Startup.cs，编辑ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //Swagger
            services.AddSwaggerGen(c => 
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = $"{ApiName} 接口文档-- .netCore3.0",
                    Description = $"{ApiName} 框架说明文档"

                });
                c.OrderActionsBy(o => o.RelativePath);

                //配置文件
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "MyNewTest.Core.xml");
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
            });
        }

Model层添加注释和上面操作一样，只需要多加一句代码

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //Swagger
            services.AddSwaggerGen(c => 
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = $"{ApiName} 接口文档-- .netCore3.0",
                    Description = $"{ApiName} 框架说明文档"

                });
                c.OrderActionsBy(o => o.RelativePath);

                //配置文件
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "MyNewTest.Core.xml");
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改

                //model层
                var xmlModelPath = Path.Combine(AppContext.BaseDirectory, "MyNewTest.Model.xml");
                c.IncludeXmlComments(xmlModelPath);
            });
        }

6、隐藏接口
如果不想显示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]