ASP.NET Core 2.2 引入了 API 分析器，它有利於提高 API 的文檔化，API分析器 可以應用在任何帶有 ApiController 特性的 Controller 上，本篇就和大家一起討論下。
安裝 API 分析器
如果你使用的是 ASP.NET Core 2.2 的話，用 Visual Studio 中的 NuGet Package Manager 可視化面板 或者 NuGet Package Manager Console 命令行輸入如下命令安裝 Api Analyzer。
Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
值得注意的是，在 ASP.NET Core 3.0 中已經內置了 Microsoft.AspNetCore.Mvc.Api.Analyzers，所以不需要單獨安裝。
創建 model 和 repository
生成一個 Author 類，代碼如下：
public class Author
{
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
}
爲了簡單起見，我準備創建一個非常簡單的 Repository，不連接數據庫，如下代碼所示：
public class AuthorRepository
{
List<Author> authors = new List<Author>()
{
new Author
{
Id = 1,
FirstName = "Joydip",
LastName = "Kanjilal"
},
new Author
{
Id = 2,
FirstName = "Steve",
LastName = "Smith"
}
};
public async Task<Author> GetAuthor(int id)
{
var author = authors.FirstOrDefault(a => a.Id == id);
return await Task.FromResult<Author>(author);
}
public async Task<bool> SaveAuthor(Author author)
{
var result = authors.Where(a => a.Id == author.Id);
if(result == null)
{
authors.Add(author);
return await Task.FromResult(true);
}
return await Task.FromResult(false);
}
}
上面 AuthorRepository 類包含兩個方法：GetAuthor() 和 SaveAuthor()，前者用於在集合中返回 author 實例，後者用於將 author 實例插入到集合中。
創建 controller 類
接下來將 DefaultController 改造如下：
[Route("api/[controller]")]
[ApiController]
public class DefaultController : ControllerBase
{
AuthorRepository authorRepository = new AuthorRepository();
[HttpGet("{id}")]
public async Task<ActionResult<Author>> Get(int id)
{
if (id <= 0)
{
return BadRequest();
}
try
{
var author = await authorRepository.GetAuthor(id);
if (author == null)
return NotFound();
return Ok(author);
}
catch
{
return BadRequest();
}
}
[HttpPut]
public async Task<ActionResult<bool>> Put([FromBody] Author author)
{
var result = await authorRepository.GetAuthor(author.Id);
if (result == null)
return NotFound();
if (author == null)
{
return BadRequest();
}
try
{
var success = await authorRepository.SaveAuthor(author);
if (!success)
return BadRequest();
return Ok(author);
}
catch
{
return BadRequest();
}
}
}
配置 Swagger
然後通過 Nuget 將 Swashbuckle.AspNetCore 引入到項目，從而讓 API 文檔化。
Install-Package Swashbuckle.AspNetCore
當 Swashbuckle.AspNetCore 安裝完畢之後，在 Startup.ConfigureServices 方法中將 Swagger 注入到 IOC 容器中，代碼如下：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "ApiAnalyzersDemo API",
Version = "v1"});
});
AddSwaggerGen 擴展方法主要是用來指定 API 文檔的元數據，通常情況下還要啓動 Swagger UI 來實現可視化，在 Startup.Configure 方法中增加如下代碼。
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
});
瀏覽 Swagger UI 端點地址
現在把程序跑起來，輸入地址：http://localhost:51787/swagger/index.html， 你會看到如下 API 文檔化界面。
值得注意的是，Swagger 默認只會列出 HttpStatus =200 的 Response 信息，如下圖：
如果想讓 Swagger 多列幾種狀態，要怎麼做呢？你可以在 Action 或者 Controller 上增加幾個 StatusCode 狀態即可，比如 200，400 和 404 ，修改代碼如下：
[Route("api/[controller]")]
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
public class DefaultController : ControllerBase
{
AuthorRepository authorRepository = new AuthorRepository();
[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<Author>> Get(int id)
{
if (id <= 0)
{
return BadRequest();
}
try
{
var author = await authorRepository.GetAuthor(id);
if (author == null)
return NotFound();
return Ok(author);
}
catch
{
return BadRequest();
}
}
}
然後再次執行應用程序看下頁面輸出。
完整的 分析器 代碼
下面是完整的 DefaultController 代碼，可供參考。
[Route("api/[controller]")]
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
public class DefaultController : ControllerBase
{
AuthorRepository authorRepository = new AuthorRepository();
[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<Author>> Get(int id)
{
if (id <= 0)
{
return BadRequest();
}
try
{
var author = await authorRepository.GetAuthor(id);
if (author == null)
return NotFound();
return Ok(author);
}
catch
{
return BadRequest();
}
}
[HttpPut]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<bool>> Put([FromBody] Author author)
{
var result = await authorRepository.GetAuthor(author.Id);
if (result == null)
return NotFound();
if (author == null)
{
return BadRequest();
}
try
{
var success = await authorRepository.SaveAuthor(author);
if (!success)
return BadRequest();
return Ok(author);
}
catch
{
return BadRequest();
}
}
}
API 分析器 是 ASP.NET Core 的一個非常好的補充，正如我們看到的，你可以利用 API Analyzers 和 Swashbuckle 來生成一個優美的 API 文檔，關於 Swashbuckle 更多的知識，參考 github: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
譯文鏈接：https://www.infoworld.com/article/3567194/how-to-use-api-analyzers-in-asp-net-core.html