Comparteix a través de

Compatibilidad con OpenAPI en aplicaciones API Apps de ASP.NET Core

  • Article

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulta la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

ASP.NET Core es compatible con la generación de documentos openAPI en API Apps mínimas y basadas en controladores. La especificación OpenAPI es un estándar independiente del lenguaje de programación para documentar las API HTTP. Este estándar es compatible con las aplicaciones ASP.NET Core mediante una combinación de API integradas y bibliotecas de código abierto. Existen tres aspectos clave para la integración de OpenAPI en una aplicación:

  • Generación de información sobre los puntos de conexión de la aplicación.
  • Recopilación de la información en un formato que se ajuste al esquema OpenAPI.
  • Exposición del documento OpenAPI generado a través de una interfaz de usuario visual o un archivo serializado.

Las aplicaciones ASP.NET Core proporcionan compatibilidad integrada para generar información sobre los puntos de conexión de una aplicación mediante el paquete Microsoft.AspNetCore.OpenApi.

El siguiente código se genera mediante la plantilla de API web mínima de ASP.NET Core y 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);
}

En el código resaltado anterior:

  • AddOpenApi registra los servicios necesarios para la generación de documentos de OpenAPI en el contenedor de inserción de dependencias de la aplicación.
  • MapOpenApi agrega un punto de conexión a la aplicación para ver el documento de OpenAPI serializado en JSON. El punto de conexión de OpenAPI está restringido al entorno de desarrollo para minimizar el riesgo de exponer información confidencial y reducir las vulnerabilidades a ataques en producción.

Paquete NuGet Microsoft.AspNetCore.OpenApi

El paquete Microsoft.AspNetCore.OpenApi proporciona las siguientes características:

  • Compatibilidad con la generación de documentos de OpenAPI en tiempo de ejecución y acceso a ellos a través de un punto de conexión en la aplicación.
  • Compatibilidad con las API "transformadoras" que permiten modificar el documento generado.

Para usar el paquete Microsoft.AspNetCore.OpenApi, agrégalo como PackageReference a un archivo de proyecto:

<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 obtener más información sobre el paquete Microsoft.AspNetCore.OpenApi, consulta Generación de documentos de OpenAPI.

Paquete NuGet Microsoft.Extensions.ApiDescription.Server

El paquete Microsoft.Extensions.ApiDescription.Server proporciona compatibilidad con la generación de documentos de OpenAPI en tiempo de compilación y su serialización.

Para usar Microsoft.Extensions.ApiDescription.Server, agrégalo como PackageReference a un archivo de proyecto. La generación de documentos en tiempo de compilación se habilita al establecer la propiedad OpenApiGenerateDocuments. De forma predeterminada, el documento OpenAPI generado se guarda en el directorio obj, pero puede personalizar el directorio de salida al establecer la propiedad 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 fuente de OpenAPI de ASP.NET Core en GitHub

Recursos adicionales

La especificación OpenAPI es un estándar independiente del lenguaje de programación para documentar las API HTTP. Este estándar se admite en las API mínimas mediante una combinación de API integradas y bibliotecas de código abierto. Existen tres aspectos clave para la integración de OpenAPI en una aplicación:

  • Generación de información sobre los puntos de conexión de la aplicación.
  • Recopilación de la información en un formato que se ajuste al esquema OpenAPI.
  • Exposición del esquema OpenAPI generado a través de una interfaz de usuario visual o de un archivo serializado.

Las API mínimas proporcionan compatibilidad integrada para generar información sobre los puntos de conexión de una aplicación mediante el paquete Microsoft.AspNetCore.OpenApi. La exposición de la definición de OpenAPI generada a través de una interfaz de usuario visual requiere un paquete de terceros.

Para obtener información sobre la compatibilidad con OpenAPI en API basadas en controladores, consulta la versión .NET 9 de este artículo.