根据前两篇的介绍,我们知道.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和路由的配置。
{
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}inFreWebApi.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和路由的配置。
{
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}inFreWebApi.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页面已经可以显示我们添加到接口的注释了。同时如果我们的接口有实体参数也可以显示出来。