使用 Web API 时，了解其各种方法对开发人员来说可能是一项挑战。 Swagger 也称为OpenAPI，解决了为 Web API 生成有用文档和帮助页的问题。 它具有诸如交互式文档、客户端 SDK 生成和 API 可发现性等优点。
Swashbuckle 有三个主要组成部分：
-
1. Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
-
2. Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。
-
3. Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。
添加Swashbuckle.AspNetCore的方法
1.从“程序包管理器控制台”窗口：
· 转到“视图” > “其他窗口” > “程序包管理器控制台”
· 导航到包含.csproj 文件的目录
· 请执行以下命令：
Install-Package Swashbuckle.AspNetCore-Version 5.0.0-rc4
2.从“管理 NuGet 程序包”对话框中：
· 右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目
· 将“包源”设置为“nuget.org”
· 确保启用“包括预发行版”选项
· 在搜索框中输入“Swashbuckle.AspNetCore”
· 从“浏览”选项卡中选择最新的“Swashbuckle.AspNetCore”包，然后单击“安装”
添加并配置 Swagger 中间件
将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("./swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
启动应用，并导航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 Swagger 规范 (swagger.json) 中。
可在 http://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API，并将其合并其他计划中。
要在应用的根(http://localhost:<port>/) 处提供 Swagger UI，请将RoutePrefix 属性设置为空字符串：
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("./swagger/v1/swagger.json", "My API V1");
c.RoutePrefix = string.Empty;
});
app.UseMvc();
}
并将launchSettings.json文件中的 "launchUrl": "api/values"注释掉
{
"$schema": "http://json.schemastore.org/launchsettings.json",
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:52655",
"sslPort": 0
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
//"launchUrl": "swagger",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"appDemo": {
"commandName": "Project",
"launchBrowser": true,
//"launchUrl": "swagger",
"applicationUrl": "http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
自定义和扩展
Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。
API 信息和说明
传递给 AddSwaggerGen 方法的配置操作会添加诸如作者、许可证和说明的信息：
public void ConfigureServices(IServiceCollection services){services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info{Version = "v1",Title = "ToDo API",Description = "A simple example ASP.NET Core Web API",TermsOfService = "https://blog.csdn.net/zhoubangbang1",Contact = new Contact{Name = "zbb",Email = string.Empty,Url = "https://blog.csdn.net/zhoubangbang1",},License = new License{Name = "Use under LICX",Url = "https://blog.csdn.net/zhoubangbang1",}});});}
运行结果：
为接口添加注释
将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如，“TodoApi.XML”文件在 Windows 上有效，但在 CentOS 上无效。
右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：
这里我用的是相对路径，可以直接生成到 api 层的 bin文件夹下
public void ConfigureServices(IServiceCollection services){services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info{Version = "v1",Title = "ToDo API",Description = "A simple example ASP.NET Core Web API",TermsOfService = "https://blog.csdn.net/zhoubangbang1",Contact = new Contact{Name = "zbb",Email = string.Empty,Url = "https://blog.csdn.net/zhoubangbang1",},License = new License{Name = "Use under LICX",Url = "https://blog.csdn.net/zhoubangbang1",}});//就是这里var basePath = PlatformServices.Default.Application.ApplicationBasePath;var xmlPath = Path.Combine(basePath, " appDemo.xml");//这个就是刚刚配置的xml文件名c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改});}
此时，先别忙着运行项目，会出现很多的警告
这是因为swagger把一些接口方法都通过xml文件配置了。
如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：
最后的运行结果：
请关注我的微信公众号，我们一起进步：
