用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

Swagger是一个描述RESTful的Web API的规范和框架。如果使用ASP.NET的话，可以用Swashbuckle来自动生成Swagger,具体参考如何使 WebAPI 自动生成漂亮又实用在线API文档。下面详细的介绍一下如何给ASP.NET Core的项目自动生成Swagger的API帮助文档。

创建ASP.NET Core的Web API Controller

在Visual Studio 2015中创建一个ASP.NET Core的项目，点击添加“New Item”，“Server-side”，“Web API Controller Class”。Visual Studio会帮我们自动创建一个如下的文件，实现了一个标准的RESTful的Web API。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

[Route("api/[controller]")] public class ValuesController : Controller {    // GET: api/values    [HttpGet]    public IEnumerable<string> Get()    {        return new string[] { "value1", "value2" };    }    // GET api/values/5    [HttpGet("{id}")]    public string Get(int id)    {        return "value";    }    // POST api/values    [HttpPost]    public void Post([FromBody]string value)    {    }    // PUT api/values/5    [HttpPut("{id}")]    public void Put(int id, [FromBody]string value)    {    }    // DELETE api/values/5    [HttpDelete("{id}")]    public void Delete(int id)    {    } }

添加Swashbuckle的Nuget包

打开project.json文件，添加Swashbuckle的依赖Swashbuckle.SwaggerGen和Swashbuckle.SwaggerUi。注意我们要使用6.0的版本，这是针对ASP.NET Core的。它的github地址Ahoy也和之前的版本不一样了。

1 2 3 4 5 6 7 8 9 10

"dependencies": {  "Microsoft.AspNet.IISPlatformHandler": "1.0.0-rc1-final",  "Microsoft.AspNet.Mvc": "6.0.0-rc1-final",  "Microsoft.AspNet.Mvc.Core": "6.0.0-rc1-final",  "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final",  "Microsoft.AspNet.SignalR.Server": "3.0.0-rc1-final",  "Microsoft.AspNet.StaticFiles": "1.0.0-rc1-final",  "Swashbuckle.SwaggerGen": "6.0.0-rc1-final",  "Swashbuckle.SwaggerUi": "6.0.0-rc1-final" },

在Startup.cs中配置Swashbuckle

1 2 3 4 5 6 7 8 9 10 11 12 13 14

public void ConfigureServices(IServiceCollection services) {    // ...    services.AddSwaggerGen();    // ... } public void Configure(IApplicationBuilder app) {    // ...    app.UseSwaggerGen();    app.UseSwaggerUi("help"); // API文档的地址，默认是 /swagger/ui    // ... }

运行项目，查看API文档，也能直接测试

万事俱备，运行项目，打开地址，就能看到如下的API文档了，还能直接在这里测试Web API。

相关文章：

• WebAPI前置知识:HTTP与RestfulAPI
  

• WEB API系列（一）：WEB API的适用场景、第一个实例

• WEB API 系列（二） Filter的使用以及执行顺序

• ASP.NET Web API 安全筛选器

• Web API 基于ASP.NET Identity的Basic Authentication

• ASP.NET Web Api使用CacheCow和ETag缓存资源

• 使用 West Wind WebSurge 对 ASP.NET Web API 服务进行压力测试

• Web API应用支持HTTPS的经验总结

• Dion Hinchcliffe谈Web API的过去与未来

• WebAPI生成可导入到PostMan的数据

• 如何使 WebAPI 自动生成漂亮又实用在线API文档
  

原文地址：http://fresky.github.io/2016/06/08/use-swashbuckle-to-add-swagger-api-help-for-asp-net-core/

---

.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注