Поддержка OpenAPI в приложениях API ASP.NET Core

ASP.NET Core поддерживает создание документов OpenAPI в приложениях на основе контроллера и минимальных API. Спецификация OpenAPI — это стандарт программирования, не зависящий от языка для документирования API HTTP. Этот стандарт поддерживается в приложениях ASP.NET Core с помощью сочетания встроенных API и библиотек с открытым кодом. В приложении существует три ключевых аспекта интеграции OpenAPI:

• Создание сведений о конечных точках в приложении.
• Сбор сведений в формате, который соответствует схеме OpenAPI.
• Предоставление созданного документа OpenAPI с помощью визуального интерфейса или сериализованного файла.

ASP.NET Приложения Core предоставляют встроенную поддержку создания сведений о конечных точках в приложении с помощью Microsoft.AspNetCore.OpenApi пакета.

Следующий код создается шаблоном ASP.NET Core для минимального веб-API и использует стандарт 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);
}

В предыдущем выделенном коде:

• AddOpenApi регистрирует службы, необходимые для создания документов OpenAPI, в контейнер DI приложения.
• MapOpenApi добавляет конечную точку в приложение для просмотра документа OpenAPI, сериализованного в JSON. Конечная точка OpenAPI ограничена средой разработки, чтобы свести к минимуму риск предоставления конфиденциальной информации и снизить уязвимости в рабочей среде.

Пакет Microsoft.AspNetCore.OpenApi предоставляет следующие функции:

• Поддержка создания документов OpenAPI во время выполнения и доступа к ним через конечную точку приложения.
• Поддержка API-интерфейсов "преобразователя", позволяющих изменять созданный документ.

Чтобы использовать Microsoft.AspNetCore.OpenApi пакет, добавьте его как PackageReference в файл проекта:

<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>

Дополнительные сведения о пакете Microsoft.AspNetCore.OpenApi см. в статье "Создание документов OpenAPI".

Пакет Microsoft.Extensions.ApiDescription.Server обеспечивает поддержку создания документов OpenAPI во время сборки и их сериализации.

Чтобы использовать Microsoft.Extensions.ApiDescription.Serverего, добавьте его как PackageReference в файл проекта. Создание документов во время сборки включено, задав OpenApiGenerateDocuments свойство. По умолчанию созданный документ OpenAPI сохраняется в obj каталоге, но можно настроить выходной каталог, задав 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>

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

• Проверка подлинности и авторизация в минимальных API

Спецификация OpenAPI — это стандарт программирования, не зависящий от языка для документирования API HTTP. Этот стандарт поддерживается в минимальных API с помощью сочетания встроенных API и библиотек с открытым кодом. В приложении существует три ключевых аспекта интеграции OpenAPI:

• Создание сведений о конечных точках в приложении.
• Сбор сведений в формате, который соответствует схеме OpenAPI.
• Предоставление созданной схемы OpenAPI с помощью визуального интерфейса или сериализованного файла.

Минимальные API обеспечивают встроенную поддержку создания сведений о конечных точках в приложении с помощью Microsoft.AspNetCore.OpenApi пакета. Для предоставления созданного определения OpenAPI через визуальный пользовательский интерфейс требуется сторонний пакет.

Сведения о поддержке OpenAPI в API на основе контроллеров см. в версии .NET 9 этой статьи.