正文
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" }
});
});
}
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页面已经可以显示我们添加到接口的注释了。同时如果我们的接口有实体参数也可以显示出来。
