0x00 安装 Swashbuckle 6.0
打开程序包管理器控制台，输入：
Install-Package Swashbuckle -Pre
0x01 配置 Startup.cs
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddApplicationInsightsTelemetry(Configuration);
services.AddMvc();
// 下面是具体的配置
services.AddSwaggerGen(c =>
{
c.SingleApiVersion(new Info
{
Version = "v1", // 这个属性必须要填，否则会引发一个异常
Title = "BookList API 文档",
Description = "书单的 API 文档"
});
});
services.ConfigureSwaggerGen(c =>
{
// 配置生成的 xml 注释文档路径
c.IncludeXmlComments(GetXmlCommentsPath());
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();
app.UseApplicationInsightsRequestTelemetry();
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseBrowserLink();
}
else
{
app.UseExceptionHandler("/Home/Error");
}
app.UseApplicationInsightsExceptionTelemetry();
app.UseStaticFiles();
app.UseSwagger();
app.UseSwaggerUi("doc/api"); // 配置 api 文档的访问路径
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}
下面是获取xml文档路径的方法
private string GetXmlCommentsPath()
{
var app = PlatformServices.Default.Application;
return Path.Combine(app.ApplicationBasePath, Path.ChangeExtension(app.ApplicationName, "xml"));
}
0x03 配置项目属性
在 VS 的菜单中，项目 -- 属性 -- 生成 -- Output -- XML documentation file 打上勾
0x04 尽情使用生成的文档吧！
访问 localhost:*****/doc/api 就可以看到生成的文档
这里的路径是我在上面配置的，默认的路径是 swagger/ui