Создание документов 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 CLI

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

dotnet add package Microsoft.AspNetCore.OpenApi

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

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

• Добавляет службы OpenAPI с помощью метода расширения AddOpenApi в коллекции служб построителя приложений.
• Назначает конечную точку для просмотра документа OpenAPI в формате JSON с помощью метода расширения MapOpenApi в приложении.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    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 ни в маршруте, ни в запросе, можно столкнуться с непредвиденным поведением.

Настройка конечной точки 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();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi()
        .CacheOutput();
}

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

app.Run();

Создание нескольких документов OpenAPI

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

• Создание документации OpenAPI для разных аудиторий, таких как общедоступные и внутренние API.
• Генерация документации OpenAPI для различных версий API.
• Создание документации OpenAPI для различных частей приложения, таких как интерфейсный и внутренний API.

Чтобы создать несколько документов OpenAPI, вызовите метод расширения AddOpenApi один раз для каждого документа, указав другое имя документа в первом параметре каждый раз.

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

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

Фреймворк использует метод делегата ShouldInclude от OpenApiOptions, чтобы определить, какие конечные точки включить в каждый документ.

Для каждого документа метод делегата ShouldInclude вызывается для каждой конечной точки в приложении, передавая объект ApiDescription для этой конечной точки. Метод возвращает логическое значение, указывающее, должна ли конечная точка быть включена в документ. Объект ApiDescription:

• содержит сведения о конечной точке, например метод HTTP, маршрут и типы ответов.
• Метаданные, подключенные к конечной точке с помощью атрибутов или методов расширения.

Реализация этого делегата по умолчанию использует поле GroupName из ApiDescription. Делегат задается на конечной точке с помощью метода расширения WithGroupName или атрибута EndpointGroupNameAttribute. WithGroupName или атрибут EndpointGroupName определяет, какие конечные точки следует включить в документ. Любая конечная точка, которой не было назначено имя группы, включена во все документы OpenAPI.

    // Include endpoints without a group name or with a group name that matches the document name
    ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName;    

Вы можете настроить метод делегата ShouldInclude для включения или исключения конечных точек на основе любого выбранного критерия.

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

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

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

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

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

Visual Studio

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

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

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

dotnet add package Microsoft.Extensions.ApiDescription.Server

После установки этот пакет:

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

Если зарегистрировано несколько документов, и имя документа неv1, оно исправлено с именем документа. Пример: {ProjectName}_{DocumentName}.json.

Visual Studio Code

dotnet build
type obj\{ProjectName}.json

.NET Core CLI

dotnet build
cat obj/{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. Несколько документов OpenAPI могут создаваться для разных версий API или различать общедоступные и внутренние API. По умолчанию генератор документов во время сборки выдает файлы для всех документов, настроенных в приложении. Чтобы выполнять действия только для одного имени документа, задайте аргумент --document-name в свойстве OpenApiGenerateDocumentsOptions.

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

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

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

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

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

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

var myKeyValue = app.Configuration["MyKey"];

app.MapGet("/", () => {
    return Results.Ok($"The value of MyKey is: {myKeyValue}");
})
.WithName("TestKey");

app.Run();

AddServiceDefaults добавляет общие службы .NET Aspire, такие как диспетчеризация служб, отказоустойчивость, мониторинг состояния и OpenTelemetry.

Обрезка и нативный AOT

OpenAPI в ASP.NET Core поддерживает обрезку и собственный AOT. Следующие шаги по созданию и публикации приложения OpenAPI с обрезкой и собственным AOT:

Создайте проект ASP.NET Core Web API (Native AOT).

dotnet new webapiaot

Добавьте пакет Microsoft.AspNetCore.OpenAPI.

dotnet add package Microsoft.AspNetCore.OpenApi

Обновите Program.cs, чтобы включить создание документов OpenAPI.

+ builder.Services.AddOpenApi();

var app = builder.Build();

+ app.MapOpenApi();

Опубликуйте приложение.

dotnet publish