web API .net - .net core 对比学习-使用Swagger

根据前两篇的介绍，我们知道.net web api 和 .net core web api在配置方面的不同如下：

1. .net web api的配置是在 App_Stat文件夹里面添加对应的配置类，然后在Global.asax.cs文件里面注册。

2. .net web api的配置是在Startup文件的Config和ConfigService方法里面添加注册。

对于swagger的配置,与上面的类似，我们来看一下如何在.net web api 和 .net core api项目中添加swagger.

1. 添加nuget包。

左边是.net core 需要使用的包：Swashbuckle.AspNetCore

右边是.net需要使用的包： Swashbuckle 和 Swashbuckle.Core

2. 配置使用swagger.

对于.net core web api项目我们在Startup中的ConfigService和Config方法中添加以下代码。下面的代码省去了添加MVC和路由的配置。

public void ConfigureServices(IServiceCollection services)
{
 //添加swagger文档
 services.AddSwaggerGen(
  c => {
   c.SwaggerDoc("v1", new Info
   {
    Title = "Test Api",
    Version = "v1",
    Description = "Swagger学习",
    TermsOfService = "Note",
    Contact = new Contact { Name = "Email", Email = "test@163.com", Url = "https://home.cnblogs.com/u/ZhangDamon" }
   });
  });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSwaggerUI(
        c => {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test Web API");
        });

}

对于.net web api项目，当安装完nuget包之后，在App_Start文件夹中会自动生成SwaggerConfig.cs文件。我们删除里面的注释，保留以下代码。

using System.Web.Http;
using WebActivatorEx;
using FreWebApi;
using Swashbuckle.Application;
using Swashbuckle.Swagger;
using System.Collections.Generic;
using System.Web.Http.Description;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace FreWebApi
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "FreWebApi");
                        c.IncludeXmlComments(GetXmlCommentsPath());
                        //c.OperationFilter<HttpHeaderFilter>();

                    })
                .EnableSwaggerUi(c =>
                    {
                        c.InjectJavaScript(thisAssembly, "SwaggerDemo.Scripts.swaggerui.swagger_lang.js");
                    });
        }

        private static string GetXmlCommentsPath()
        {
            return string.Format(@"{0}\bin\FreWebApi.xml", System.AppDomain.CurrentDomain.BaseDirectory);
        }
    }
}

这个时候我们打开运行然后浏览器中输入swagger地址，就可以看到swagger ui界面了。

根据前两篇的介绍，我们知道.net web api 和 .net core web api在配置方面的不同如下：

1. .net web api的配置是在 App_Stat文件夹里面添加对应的配置类，然后在Global.asax.cs文件里面注册。

2. .net web api的配置是在Startup文件的Config和ConfigService方法里面添加注册。

对于swagger的配置,与上面的类似，我们来看一下如何在.net web api 和 .net core api项目中添加swagger.

1. 添加nuget包。

左边是.net core 需要使用的包：Swashbuckle.AspNetCore

右边是.net需要使用的包： Swashbuckle 和 Swashbuckle.Core

2. 配置使用swagger.

对于.net core web api项目我们在Startup中的ConfigService和Config方法中添加以下代码。下面的代码省去了添加MVC和路由的配置。

public void ConfigureServices(IServiceCollection services)
{

 //添加swagger文档
 services.AddSwaggerGen(
  c => {
   c.SwaggerDoc("v1", new Info
   {
    Title = "Test Api",
    Version = "v1",
    Description = "Swagger学习",
    TermsOfService = "Note",
    Contact = new Contact { Name = "Email", Email = "test@163.com", Url = "https://home.cnblogs.com/u/ZhangDamon" }
   });
  });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSwaggerUI(
        c => {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test Web API");
        });

}

对于.net web api项目，当安装完nuget包之后，在App_Start文件夹中会自动生成SwaggerConfig.cs文件。我们删除里面的注释，保留以下代码。

using System.Web.Http;
using WebActivatorEx;
using FreWebApi;
using Swashbuckle.Application;
using Swashbuckle.Swagger;
using System.Collections.Generic;
using System.Web.Http.Description;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace FreWebApi
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "FreWebApi");
                        c.IncludeXmlComments(GetXmlCommentsPath());
                        //c.OperationFilter<HttpHeaderFilter>();

                    })
                .EnableSwaggerUi(c =>
                    {
                        c.InjectJavaScript(thisAssembly, "SwaggerDemo.Scripts.swaggerui.swagger_lang.js");
                    });
        }

        private static string GetXmlCommentsPath()
        {
            return string.Format(@"{0}\bin\FreWebApi.xml", System.AppDomain.CurrentDomain.BaseDirectory);
        }
    }
}

这个时候我们打开运行然后浏览器中输入swagger地址，就可以看到swagger ui界面了。

下图是.net core web api的swagger页面。

下图是.net api生产的页面。

由上面的图我们可以看到两个swagger除了访问的url不同之外就是.net core的swagger多了一些标签。

这些都是由下面的代码生成的，至于对应关系大家可以自己研究一下。

有的同学可能觉得奇怪，为什么我们这次不需要在Global.asax.cs文件里面注册swagger的配置，我们回顾一下SwaggerConfig的代码，里面下面这有下面这个特性，它可以指定在web api 启动的时候自动注册swagger的配置。

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

3. 注释文档的配置

对于.net 和.net core 来说生产文档注释的配置基本类似，首先我们需要添加xml路径，右击项目->属性->生产，选择输出路径，一般情况下都会有个默认路径不需要修改。

第二步，如果是.net项目我们在SwaggerConfig类里面修改代码如下：

对于.net core项目我们按照以下方式修改代码：

这样我们再次打开swagger就可以看到我们的swagger页面已经可以显示我们添加到接口的注释了。同时如果我们的接口有实体参数也可以显示出来。