如何在 ASP.NET Core 中使用 API Analyzer

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 authors = new List()
        {
            new Author
            {
                Id = 1,
                FirstName = "Joydip",
                LastName = "Kanjilal"
            },
            new Author
            {
                Id = 2,
                FirstName = "Steve",
                LastName = "Smith"
            }
        };
        public async Task GetAuthor(int id)
        {           
            var author = authors.FirstOrDefault(a => a.Id == id);
            return await Task.FromResult(author);
        }
        public async Task 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> 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> 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 端點地址

現在把程式跑起來，輸入地址：， 你會看到如下 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> 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> 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> 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: github.com/domaindrivendev/Swashbuckle.AspNetCore

更多高質量乾貨：參見我的 GitHub: [csharptranslate] github.com/ctripxchuang/csharptranslate