Suporte a OpenAPI em aplicativos de API ASP.NET Core

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

• Geração de informações sobre os pontos de extremidade no aplicativo.
• Reunindo as informações em um formato que corresponde ao esquema OpenAPI.
• Expor o documento OpenAPI gerado através de uma interface do usuário visual ou um arquivo serializado.

ASP.NET Core aplicações fornecem suporte interno para gerar informações sobre endpoints em uma aplicação por meio do pacote Microsoft.AspNetCore.OpenApi.

O código a seguir é gerado pelo modelo de API da Web mínima do ASP.NET Core e usa 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 anterior destacado:

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

Microsoft.AspNetCore.OpenApi pacote NuGet

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

• Suporte para gerar documentos OpenAPI em tempo de execução e acessá-los através de um endpoint no aplicativo.
• Suporte para APIs "transformer" que permitem modificar o documento gerado.

Para usar o Microsoft.AspNetCore.OpenApi pacote, 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 Microsoft.AspNetCore.OpenApi pacote, consulte Gerar documentos OpenAPI.

Microsoft.Extensions.ApiDescription.Server pacote NuGet

O Microsoft.Extensions.ApiDescription.Server pacote fornece suporte para gerar documentos OpenAPI em tempo de compilação e serializá-los.

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

<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 API v. Ponto final 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 Aplicações)

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 web em geral, "API" normalmente refere-se a um serviço web que expõe funcionalidades através de HTTP.

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

As convenções de nomenclatura internas do ASP.NET Core às vezes usam "API" de forma diferente. Por exemplo, no API Explorer, um "ApiDescription" na verdade representa uma operação de API em vez do serviço de API completo. Esta distinção reflete convenções internas de nomenclatura e, por vezes, difere da definição mais ampla aqui utilizada.

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

Operação da API

Uma operação de API representa uma ação ou recurso específico que uma API fornece. No ASP.NET Core, isto corresponde a:

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

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

Ponto de extremidade da API

Um ponto de extremidade da API é uma URL específica:

• Isso representa um recurso ou funcionalidade específica exposta 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 suportados:

• Para APIs baseadas em controladores, os pontos de extremidade combinam o esquema de rota com o controlador e a ação.
• Para APIs mínimas, os pontos de extremidade são explicitamente definidos 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 endpoints geralmente incluem parâmetros de consulta, por exemplo, GET /api/products?category=electronics&sort=price

Documentação OpenAPI

No contexto da OpenAPI, a documentação descreve a API como um todo, incluindo todos os seus endpoints e operações. A 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 OpenAPI. A especificação OpenAPI organiza a documentação por operações, que são agrupadas por caminhos (endpoints). 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, PUT, etc.) definem as operações
• Cada operação contém detalhes sobre parâmetros, corpo da solicitação, respostas, etc.

Exemplo no formato JSON 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": {...}
      }
    }
  }
}

Comparação entre API, operação de API e endpoint 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 da API	Ponto de extremidade da API
Definição	Uma descrição lógica de uma ação da API: método + caminho + comportamento	A verdadeira rota HTTP configurada que escuta pedidos
Nível	Conceitualmente, quais ações podem ocorrer	Concretamente, que URL e método são correspondidos
Ligado a	Design/especificação da API OpenAPI	ASP.NET Roteamento principal em tempo de execução
Descreve	O que a API faz, por exemplo, "criar produto"	Onde e como chamá-lo, por exemplo, POST https://localhost:7099/api/products, POST https://contoso.com/api/products
Em ASP.NET núcleo	Ações de controlador ou métodos da API mínima, antes de o roteamento ser resolvido	Objetos de endpoint resolvidos em tempo de execução

ASP.NET Código-fonte OpenAPI principal no GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Recursos adicionais

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