Suporte a OpenAPI em aplicativos de API do ASP.NET Core

O ASP.NET Core oferece suporte à geração de documentos OpenAPI em aplicativos de APIs mínimas e baseados em controlador. A especificação do OpenAPI é um padrão independente de linguagem de programação para documentar APIs HTTP. Esse padrão tem suporte em aplicativos ASP.NET Core por meio de uma combinação de APIs internas e bibliotecas de código aberto. Há três aspectos principais para a integração do OpenAPI em um aplicativo:

• Gerando informações sobre os pontos de extremidade no aplicativo.
• Coletando as informações em um formato que corresponde ao esquema do OpenAPI.
• Expondo o documento OpenAPI gerado por meio de uma interface visual ou de um arquivo serializado.

Os aplicativos ASP.NET Core oferecem suporte interno para gerar informações sobre pontos de extremidade em um aplicativo por meio do pacote Microsoft.AspNetCore.OpenApi.

O código a seguir é gerado pelo modelo de API Web mínima do ASP.NET Core e usa o OpenAPI:

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

No código realçado anterior:

• AddOpenApi registra os serviços necessários para a geração de documentos OpenAPI no contêiner DI do aplicativo.
• MapOpenApi adiciona um ponto de extremidade ao aplicativo para visualizar o documento OpenAPI serializado em JSON. O ponto de extremidade do OpenAPI é restrito ao ambiente de desenvolvimento para minimizar o risco de exposição de informações confidenciais e reduzir as vulnerabilidades na produção.

Pacote NuGet Microsoft.AspNetCore.OpenApi

O pacote Microsoft.AspNetCore.OpenApi fornece os seguintes recursos:

• Suporte para geração de documentos OpenAPI em tempo de execução e acesso a esses documentos por meio de um ponto de extremidade no aplicativo.
• Suporte para APIs "transformadoras" que permitem modificar o documento gerado.

Para usar o pacote Microsoft.AspNetCore.OpenApi, adicione-o como um PackageReference a um arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Para saber mais sobre o pacote Microsoft.AspNetCore.OpenApi, consulte Gerar documentos do OpenAPI.

Pacote NuGet Microsoft.Extensions.ApiDescription.Server

O pacote Microsoft.Extensions.ApiDescription.Server oferece suporte para geração de documentos OpenAPI no momento da compilação e serialização desses documentos.

Para usar Microsoft.Extensions.ApiDescription.Server, adicione-a como um PackageReference a um arquivo de projeto: A geração de documentos no momento da compilação é habilitada ao definir a propriedade OpenApiGenerateDocuments. Por padrão, o documento OpenAPI gerado é salvo no diretório obj, mas você pode personalizar o diretório de saída definindo a propriedade OpenApiDocumentsDirectory.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

API v. Operação da API v. Endpoint de API

As seções a seguir explicam as diferenças entre uma API, um ponto de extremidade de API e uma operação de API no contexto da documentação ASP.NET Core e OpenAPI.

API (Interface de Programação de Aplicativo)

Uma API é um conjunto de regras e protocolos para criar e interagir com aplicativos de software. Ele define como diferentes componentes de software devem se comunicar. No desenvolvimento geral da Web, "API" normalmente se refere a um serviço Web que expõe a funcionalidade via HTTP.

No ASP.NET Core, uma API geralmente é criada usando controladores ou APIs mínimas, que lidam com solicitações HTTP de entrada e retornam respostas.

as convenções de nomenclatura interna do ASP.NET Core às vezes usam "API" de forma diferente. Por exemplo, no Gerenciador de API, uma "ApiDescription" representa, na verdade, uma Operação de API em vez do serviço de API completo. Essa distinção reflete as convenções de nomenclatura internas e, às vezes, difere da definição mais ampla usada aqui.

Consulte Introdução ao ApiExplorer no ASP.NET Core para obter mais informações sobre o Gerenciador de API.

Operação de API

Uma operação de API representa uma ação ou uma funcionalidade específica que uma API fornece. No ASP.NET Core, isso corresponde a:

• Métodos de ação do controlador em APIs no estilo MVC
• Manipuladores de rotas em APIs mínimas

Cada operação é definida por seu método HTTP (GET, , POSTetc PUT.), caminho, parâmetros e respostas.

Ponto de Extremidade de API

Um endpoint de API é uma URL específica:

• Isso representa um recurso ou funcionalidade específico exposto pela API.
• Fornece o endereço exato para o qual um cliente precisa enviar uma solicitação HTTP para interagir com uma operação de API específica.

Um ponto de extremidade é uma combinação da URL base da API e um caminho específico para o recurso desejado, juntamente com os métodos HTTP compatíveis:

• Para APIs baseadas em controlador, os pontos de extremidade combinam o modelo de rota com o controlador e a ação.
• Para APIs mínimas, os pontos de extremidade são definidos explicitamente com app.MapGet(), app.MapPost()etc.

Por exemplo, o api/products/{id} endpoint que suporta as seguintes operações:

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Os pontos de extremidade geralmente incluem parâmetros de consulta, por exemplo, GET /api/products?category=electronics&sort=price

Documentação do OpenAPI

No contexto do OpenAPI, a documentação descreve a API como um todo, incluindo todos os seus pontos de extremidade e operações. O OpenAPI fornece uma maneira estruturada de documentar APIs, tornando mais fácil para os desenvolvedores entenderem como interagir com elas.

As Operações de API são o foco principal da documentação do OpenAPI. A especificação OpenAPI organiza a documentação por operações, que são agrupadas por caminhos (pontos de extremidade). Cada operação é descrita com detalhes como parâmetros, corpos de solicitação, respostas e muito mais. Esse formato estruturado permite que as ferramentas gerem bibliotecas de clientes, stubs de servidor e documentação interativa automaticamente.

Em um documento OpenAPI:

• O documento inteiro descreve a API como um todo
• Cada item de caminho (como /api/products/{id}) representa um ponto de extremidade
• Em cada caminho, os métodos HTTP (GET, POST, PUTetc.) definem as operações
• Cada operação contém detalhes sobre parâmetros, corpo da solicitação, respostas etc.

Exemplo no formato JSON do OpenAPI:

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

API, operação de API e comparação de endpoints de API

A tabela a seguir resume as diferenças entre uma API, uma operação de API e um ponto de extremidade de API:

Conceito	Operação de API	Ponto de Extremidade de API
Definição	Uma descrição lógica de uma ação de API: método + caminho + comportamento	A rota HTTP realmente configurada que escuta solicitações
Nível	Conceitualmente, que ação pode ocorrer?	Especificamente, qual URL e método correspondem
Vinculado a	Design/especificação da API OpenAPI	Roteamento do ASP.NET Core em runtime
Descreve	O que a API faz, por exemplo, "criar produto"	Onde e como chamá-lo, por exemplo: POST https://localhost:7099/api/products e POST https://contoso.com/api/products
No ASP.NET Core	Ações do controlador ou métodos mínimos de API, antes que o roteamento seja resolvido	Objetos de endpoint resolvidos em tempo de execução

Código-fonte do ASP.NET Core OpenAPI no GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Recursos adicionais

• Autenticação e autorização em APIs mínimas