对于构建一个消费应用程序，理解API的各个方法对开发这是一个不小的挑战。为了使你的API更利于阅读。
使用Swagger为你的Web API生成好的文档和帮助页,.NET Core实现了Swashbuckle.AspNetCore，，使用Swagger是非常简单的，只需添加一组Nuget包和修改Startup就可以搞定。
.Swashbuckle.AspNetCore 开源项目, ASP.NET Core Web API生成Swagger文档的
.Swagger是一个机器可读的restful风格的api接口的代表。他可以支持文档交互客户端sdk生成，并且具有可见性
1、入门
三个主要组件：
Swashbuck.AspNetCore.Swagger：Swagger对象模型和中间件，作为JSON终结点公开SwaggerDocument对象。
Swashbuckle.AspNetCore.SwaggerGen：一个Swagger生成器,可以直接从路由、控制器、模型构建SwaggerDocument对象。他通常和Swagger终结点中间件结合，以自动公开SwaggerJson
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本，Swagger UI工具的嵌入式版本，它将Swagger JSON解释为构建丰富的，可定制的Web API功能描述体验。 它包括公共方法的内置测试线束。
2、通过下面命令安装这三个组件
可以使用下面方法添加Swashbuckle
Install-Package Swashbuckle.AspNetCore
3、添加并配置到Swagger到中间件
将Swagger生成器添加到Startup.cs的ConfigureServices方法中。
public void ConfigureServices(IServiceCollection services) { services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList")); services.AddMvc(); //注册Swagger生成器，定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); }); }
Info类包含在Swashbuckle.AspNetCore.Swagger命名空间中。
在Startup.cs类的Configure方法中。启用中间件服务，主要生成JSON文档和SwaggerUI.
public void Configure(IApplicationBuilder app) { //启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui，指定Swagger JSON终结点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); app.UseMvc(); }
启动App,导航到:<random_port>/swagger/v1/swagger.json ，显示描述终结点的文档。
可以通过浏览:<random_port>/swagger来查看生成的Swagger UI。
TodoController中的每个公共操作方法都可以从UI进行测试。单击一个方法名称可以展开节点。添加参数，单机"测试"!
4、定制和可扩展性
Swagger提供了用于记录对象模型和自定义UI。
API Info and Description通过将一些信息传递给AddSwaggerGen方法，如author、license和description
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1", Title = "ToDo API", Description = "A simple example ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "https://twitter.com/spboyer" }, License = new License { Name = "Use under LICX", Url = "https://example.com/license" } }); });
下面图片描述了Swagger UI显示的版本信息
启用XML注释
配置Swagger，让Swagger使用生成的XML文件。对于Linux和非Window操作系统，文件名和路径可以区分大小写。
public void ConfigureServices(IServiceCollection services) { services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList")); services.AddMvc(); // Register the Swagger generator, defining one or more Swagger documents services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1", Title = "ToDo API", Description = "A simple example ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "https://twitter.com/spboyer" }, License = new License { Name = "Use under LICX", Url = "https://example.com/license" } }); // Set the comments path for the Swagger JSON and UI. var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "TodoApi.xml"); c.IncludeXmlComments(xmlPath); }); }