Использование документов openAPI

Использование пользовательского интерфейса Swagger для локального нерегламентированного тестирования

По умолчанию Microsoft.AspNetCore.OpenApi пакет не предоставляет встроенную поддержку визуализации или взаимодействия с документом OpenAPI. Популярные инструменты для визуализации или взаимодействия с документом OpenAPI включают пользовательский интерфейс Swagger и ReDoc. Пользовательский интерфейс Swagger и ReDoc можно интегрировать в приложение несколькими способами. Редакторы, такие как Visual Studio и Visual Studio Code, предлагают расширения и встроенные возможности для тестирования в документе OpenAPI.

Пакет Swashbuckle.AspNetCore.SwaggerUi предоставляет пакет веб-ресурсов пользовательского интерфейса Swagger для использования в приложениях. Этот пакет можно использовать для отрисовки пользовательского интерфейса для созданного документа. Чтобы настроить это:

• Установите пакет Swashbuckle.AspNetCore.SwaggerUi.
• Включите промежуточное программное обеспечение swagger-ui со ссылкой на маршрут OpenAPI, зарегистрированный ранее.

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.AddOpenApi();

var app = builder.Build();

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

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

app.Run();

В качестве рекомендации по обеспечению безопасности для ограничения раскрытия информации в средах разработки следует включить пользовательские интерфейсы OpenAPI (пользовательский интерфейс Swagger, ReDoc, Scalar). Например, см. конфигурацию Swagger OAuth 2.0.

Запустите приложение и перейдите к https://localhost:<port>/swagger, чтобы просмотреть пользовательский интерфейс Swagger.

Чтобы автоматически запустить приложение по URL-адресу пользовательского интерфейса Swagger с помощью https профиля Properties/launchSettings.json:

• Убедитесь, что launchBrowser включена (true).
• Задайте для launchUrl значение swagger.

"launchBrowser": true,
"launchUrl": "swagger",

Использование Scalar для интерактивной документации по API

Скаляр — это интерактивный интерфейс интерактивного документа с открытым кодом для OpenAPI. Скаляр может интегрироваться с конечной точкой OpenAPI, предоставляемой ASP.NET Core. Чтобы настроить Scalar, установите Scalar.AspNetCore пакет.

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Запустите приложение и перейдите к https://localhost:<port>/scalar, чтобы просмотреть скалярный пользовательский интерфейс.

Чтобы автоматически запустить приложение по URL-адресу скалярного пользовательского интерфейса с помощью https профиля Properties/launchSettings.json:

• Убедитесь, что launchBrowser включена (true).
• Задайте для launchUrl значение scalar.

"launchBrowser": true,
"launchUrl": "scalar",

Lint создал документы OpenAPI с помощью Spectral

Spectral — это линтер для документов OpenAPI с открытым исходным кодом. Spectral можно включить в сборку приложения, чтобы проверить качество созданных документов OpenAPI. Установите Spectral в соответствии с инструкциями по установке пакета.

Чтобы воспользоваться преимуществами Spectral для проверки документов OpenAPI на этапе сборки, сначала установите пакет Microsoft.Extensions.ApiDescription.Server, чтобы обеспечить их генерацию на этом этапе.

Включите создание документов во время сборки, задав следующие свойства в файле приложения .csproj :

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

Запустите dotnet build , чтобы создать документ.

dotnet build

.spectral.yml Создайте файл со следующим содержимым.

extends: ["spectral:oas"]

Запустите spectral lint на созданном файле.

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Поддержка внедрения IOpenApiDocumentProvider

Вы можете внедрить IOpenApiDocumentProvider в ваши службы через внедрение зависимостей, чтобы программно получить доступ к документам OpenAPI, даже вне контекстов HTTP-запросов.

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

Зарегистрируйте службу в контейнере DI:

builder.Services.AddScoped<DocumentService>();

Это позволяет выполнять такие сценарии, как создание клиентских пакетов SDK, проверка контрактов API в фоновых процессах или экспорт документов во внешние системы.

Поддержка внедрения IOpenApiDocumentProvider была введена в ASP.NET Core в .NET 10. Дополнительные сведения, см. в dotnet/aspnetcore #61463.