使用 ASP.NET Core 5 Web API 创建可发现的 HTTP API

https://devblogs.microsoft.com/aspnet/creating-discoverable-http-apis-with-asp-net-core-5-web-api/

这个月，我们将关注使用 .NET 5 创建 HTTP API。我们将探索各种不同的工具、技术和服务来使你的 API 开发体验更为愉快。每一周，我们将在本博客发布一篇关于使用 .NET 构建 HTTP API 不同领域的文章，主要关注于使用 ASP.NET Core 5 Web API 和 OpenAPI 标准两者来构建、发布、消费和重用良好说明的 Web。下面是寄到到来的一个系列。

Creating Discoverable HTTP APIs with ASP.NET Core 5 Web API (this post)
Open-source HTTP API packages and Tools
Generating HTTP API clients using Visual Studio Connected Services
App Building with Azure API Management, Power Apps, and Logic Apps

考虑设计优先

如果你曾经在 Visual Studio 中右键 Add Web Reference 来添加一个 SOAP Web 服务，或者，当 WCF 出现的时候，使用 Add Service Reference 来添加它，您就会知道这些工具及其对标准描述格式的支持（Web 服务定义语言（WSDL）为您的开发体验带来的快乐。

OpanAPI 规范

定义良好的 API 对于开发、维护和使用它是友好的。在开发过程中，使用这些包来描述你的 API，通过遵循一些简单的约定，你的 API 将更加可发现、与其它产品和云服务集成的集成会更加容易，通常来说，提供更多的使用场景。

示例项目

本文使用一个简单的 Visual Studio 解决方案。在该解决方案中，你将发现一个简单的用于 Contoso 在线订单的 Web API 工程。随着进行，

https://github.com/bradygaster/Contoso.Online.Orders?WT.mc_id=dotnet-13135-bradyg

ProducesAttribute

设定 API 输出的类型

对应的，ConsumesAttribute 用来指定请求 API 的内容类型。

[Produces("application/json")]
[Consumes("application/json")]

还可以使用 MediaTypeName 来更加简单的使用众所周知的媒体类型值。

可以在 Controller 级别为所有的请求和响应设置为 JSON 类型。

[Route("[controller]")]
[ApiController]
#if ProducesConsumes
    [Produces(MediaTypeNames.Application.Json)]
    [Consumes(MediaTypeNames.Application.Json)]
#endif
public class AdminController : ControllerBase
{
    // controller code
}

HTTP Response Codes

如果成功，返回 200 OK，和实际的产品。

否则，会返回 404

[HttpGet("/products/{id}")]
public async Task<ActionResult<Product>> GetProduct(int id)
{
    var product = StoreServices.GetProduct(id);

    if(product == null)
    {
        return NotFound();
    }
    else
    {
        return Ok(product);
    }
}

但是，OpenAPI 的 JSON 对于该方法仅仅提供了 200 响应码，默认的 GET 行为。

Web API 约定

见：https://docs.microsoft.com/zh-cn/aspnet/core/web-api/advanced/conventions?view=aspnetcore-5.0&WT.mc_id=dotnet-13135-bradyg

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

#if ApiConventions
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
#endif

namespace ContosoOnlineOrders.Api
{
    public class Program
    {