Поддержка 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 ограничена средой разработки, чтобы свести к минимуму риск предоставления конфиденциальной информации и снизить уязвимости в рабочей среде.

пакет NuGet Microsoft.AspNetCore.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".

пакет NuGet Microsoft.Extensions.ApiDescription.Server;

Пакет 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>

API v. Операция API v. Конечная точка API

В следующих разделах описываются различия между API, конечной точкой API и операцией API в контексте документации ASP.NET Core и OpenAPI.

API (интерфейс программирования приложений)

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

В ASP.NET Core API обычно создается с помощью контроллеров или минимальных API, обрабатывающих входящие HTTP-запросы и возвращаемые ответы.

Внутренние соглашения об именовании в ASP.NET Core иногда используют API по-разному. Например, в обозревателе API "ApiDescription" фактически представляет собой операцию API, а не полную службу API. Это различие отражает внутренние соглашения об именовании и иногда отличается от более широкого определения, используемого здесь.

Дополнительные сведения об обозревателе API см. в разделе "Общие сведения об APIExplorer" в ASP.NET Core .

Операция API

Операция API представляет определенное действие или возможность, которую предоставляет API. В ASP.NET Core это соответствует следующим:

• Методы действий контроллера в API в стиле MVC
• Обработчики маршрутов в минимальных API

Каждая операция определяется методом HTTP (GET, POST, PUTи т. д.), путем, параметрами и ответами.

Конечная точка API

Конечная точка API — это конкретный URL-адрес:

• Это представляет определенный ресурс или функциональные возможности, предоставляемые API.
• Предоставляет точный адрес, в который клиент должен отправить HTTP-запрос, чтобы взаимодействовать с определенной операцией API.

Конечная точка — это сочетание базового URL-адреса API и определенного пути к требуемому ресурсу, а также поддерживаемых методов HTTP:

• Для API на основе контроллера конечные точки объединяют шаблон маршрута с контроллером и действием.
• Для минимальных API конечные точки явно определены с app.MapGet(), app.MapPost() и так далее.

Например, конечная точка api/products/{id}, поддерживающая следующие операции:

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

Конечные точки часто включают параметры запроса, например GET /api/products?category=electronics&sort=price

Документация по OpenAPI

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

Операции API — это основной фокус документации по OpenAPI. Спецификация OpenAPI упорядочивает документацию по операциям, которые группируются по путям (конечным точкам). Каждая операция описывается с такими сведениями, как параметры, текст запросов, ответы и многое другое. Этот структурированный формат позволяет средствам создавать клиентские библиотеки, заглушки сервера и интерактивную документацию автоматически.

В документе OpenAPI:

• Весь документ описывает API в целом
• Каждый элемент пути (например /api/products/{id}) представляет конечную точку
• В каждом пути методы HTTP (GET, POST, PUTи т. д.) определяют операции.
• Каждая операция содержит сведения о параметрах, тексте запроса, ответах и т. д.

Пример в формате 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": {...}
      }
    }
  }
}

Сравнение операций API, конечных точек API и самого API

В следующей таблице перечислены различия между API, операцией API и конечной точкой API:

Понятие	Операция API	Конечная точка API
Определение	Логическое описание действия API: метод + путь + поведение	Фактически настроенный HTTP-маршрут, прослушивающий запросы
Уровень	С концептуальной точки зрения, какие действия могут происходить?	Определите, какой URL-адрес и метод соответствуют
Привязка к	Проектирование и спецификация API OpenAPI	маршрутизация ASP.NET Core во время выполнения
Описывает	То, что делает API, например "создать продукт"	Где и как его вызвать, например , POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
В ASP.NET Core	Действия контроллера или минимальные методы API перед разрешением маршрутизации	Объекты конечных точек, определенные во время выполнения

Исходный код OpenAPI ASP.NET Core на GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Дополнительные ресурсы

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