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

總結

以上是生活随笔為你收集整理的如何在 ASP.NET Core 中使用 API 分析器的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。