用Swashbuckle給ASP.NET Core的項目自動生成Swagger的API幫助文檔

Swagger 是一個描述RESTful的Web API的規範和框架。若是使用ASP.NET的話，能夠用 Swashbuckle 來自動生成Swagger。下面詳細的介紹一下如何給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。

[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 也和以前的版本不同了。

"dependencies": {
  .........
  "Swashbuckle.SwaggerGen": "6.0.0-beta902",
  "Swashbuckle.SwaggerUi": "6.0.0-beta902"
},

在 Startup.cs 中配置Swashbuckle

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddSwaggerGen();
    // ...
}

public void Configure(IApplicationBuilder app)
{
    // ...
    app.UseSwaggerGen();
    app.UseSwaggerUi("help"); // API文檔的地址，默認是 /swagger/ui
    // ...
}

運行項目，查看API文檔，也能直接測試

萬事俱備，運行項目，打開地址，就能看到以下的API文檔了，還能直接在這裏測試Web API。