Compartilhar via

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

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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>

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

Recursos adicionais

A especificação do OpenAPI é um padrão independente de linguagem de programação para documentar APIs HTTP. Esse padrão tem suporte em APIs mínimas por meio de uma combinação de APIs internas e bibliotecas de software livre. 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 esquema do OpenAPI gerado por meio de uma interface do usuário visual ou um arquivo serializado.

As APIs mínimas fornecem suporte interno para gerar informações sobre pontos de extremidade em um aplicativo por meio do pacote Microsoft.AspNetCore.OpenApi. Expor a definição do OpenAPI gerada por meio de uma interface do usuário visual requer um pacote de terceiros.

Para obter informações sobre o suporte para OpenAPI em APIs baseadas em controlador, consulte a versão .NET 9 deste artigo.