Создание документов OpenAPI

Пакет Microsoft.AspNetCore.OpenApi обеспечивает встроенную поддержку создания документов OpenAPI в ASP.NET Core. Пакет предоставляет следующие функции:

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

Установка пакета

Установите пакет Microsoft.AspNetCore.OpenApi.

Visual Studio

Выполните следующую команду из консоли диспетчер пакетов:

Install-Package Microsoft.AspNetCore.OpenApi

Интерфейс командной строки.NET

Выполните следующую команду:

dotnet add package Microsoft.AspNetCore.OpenApi

Настройка создания документов OpenAPI

Следующий код:

• Добавляет службы OpenAPI.
• Включает конечную точку для просмотра документа OpenAPI в формате JSON.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

Запустите приложение и перейдите к https://localhost:<port>/openapi/v1.json просмотру созданного документа OpenAPI.

Параметры настройки создания документов OpenAPI

В следующих разделах показано, как настроить создание документов OpenAPI.

Настройка имени документа OpenAPI

Каждый документ OpenAPI в приложении имеет уникальное имя. Имя документа по умолчанию, зарегистрированного v1.

builder.Services.AddOpenApi(); // Document name is v1

Имя документа можно изменить, передав имя в качестве параметра вызову AddOpenApi .

builder.Services.AddOpenApi("internal"); // Document name is internal

Имя документа отображается в нескольких местах в реализации OpenAPI.

При получении созданного документа OpenAPI имя документа указывается в качестве documentName аргумента параметра в запросе. Следующие запросы разрешают v1 документы и internal документы.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Настройка версии OpenAPI созданного документа

По умолчанию создание документов OpenAPI создает документ, соответствующий спецификации OpenAPI версии 3.0. В следующем коде показано, как изменить версию документа OpenAPI по умолчанию:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

Настройка маршрута конечной точки OpenAPI

По умолчанию конечная точка OpenAPI, зарегистрированная с помощью вызова, предоставляет MapOpenApi документ в конечной точке /openapi/{documentName}.json . В следующем коде показано, как настроить маршрут, в котором зарегистрирован документ OpenAPI:

app.MapOpenApi("/openapi/{documentName}/openapi.json");

Возможно, но не рекомендуется удалить documentName параметр маршрута из маршрута конечной точки. documentName При удалении параметра маршрута из маршрута конечной точки платформа пытается разрешить имя документа из параметра запроса. Не предоставляя documentName маршрут или запрос, может привести к непредвиденному поведению.

Настройка конечной точки OpenAPI

Так как документ OpenAPI обслуживается через конечную точку обработчика маршрутов, любая настройка, доступная для стандартных минимальных конечных точек, доступна для конечной точки OpenAPI.

Ограничение доступа к документам OpenAPI авторизованным пользователям

Конечная точка OpenAPI не включает проверки авторизации по умолчанию. Однако проверки авторизации можно применить к документу OpenAPI. В следующем коде доступ к документу OpenAPI ограничен тем, кто имеет tester роль:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

Созданный в кэше документ OpenAPI

Документ OpenAPI создается каждый раз, когда отправляется запрос к конечной точке OpenAPI. Восстановление позволяет преобразователям включать динамическое состояние приложения в свою работу. Например, повторное создание запроса с подробными сведениями о контексте HTTP. При необходимости документ OpenAPI можно кэшировать, чтобы избежать выполнения конвейера создания документов для каждого HTTP-запроса.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

app.MapOpenApi()
    .CacheOutput();

app.MapGet("/", () => "Hello world!");

app.Run();

Создание документов OpenAPI во время сборки

В типичных веб-приложениях документы OpenAPI создаются во время выполнения и обслуживаются через HTTP-запрос на сервер приложений.

В некоторых сценариях полезно создать документ OpenAPI на этапе сборки приложения. Ниже приведены соответствующие сценарии.

• Создание документации OpenAPI, зафиксированной в системе управления версиями.
• Создание документации по OpenAPI, используемой для тестирования интеграции на основе спецификаций.
• Создание документации OpenAPI, которая обслуживается статическим образом с веб-сервера.

Чтобы добавить поддержку создания документов OpenAPI во время сборки, установите Microsoft.Extensions.ApiDescription.Server пакет:

Visual Studio

Выполните следующую команду из консоли диспетчер пакетов:

Install-Package Microsoft.Extensions.ApiDescription.Server

Интерфейс командной строки.NET

Выполните следующую команду в каталоге, который содержит файл проекта:

dotnet add package Microsoft.Extensions.ApiDescription.Server

После установки этот пакет автоматически создаст документы Open API, связанные с приложением во время сборки и заполните их в выходной каталог приложения.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Настройка создания документов во время сборки

Изменение выходного каталога созданного файла Open API

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

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

Значение OpenApiDocumentsDirectory разрешается относительно файла проекта. Используя приведенное ./ выше значение, документ OpenAPI будет выдаваться в том же каталоге, что и файл проекта.

Изменение имени выходного файла

По умолчанию созданный документ OpenAPI будет иметь то же имя, что и файл проекта приложения. Чтобы изменить имя создаваемого файла, задайте --file-name аргумент в свойстве OpenApiGenerateDocumentsOptions .

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Выбор документа OpenAPI для создания

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

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Настройка поведения во время выполнения во время сборки создания документа

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

• Не считывается из определенных строк конфигурации.
• Не регистрируя службы, связанные с базами данных.

Чтобы ограничить вызов этих кодpathов конвейером создания во время сборки, они могут быть обусловлены проверкой сборки записи следующим образом:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}