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

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

По умолчанию Microsoft.AspNetCore.OpenApi пакет не предоставляет встроенную поддержку визуализации или взаимодействия с документом OpenAPI. Популярные инструменты для визуализации или взаимодействия с документом OpenAPI включают пользовательский интерфейс Swagger и ReDoc. Пользовательский интерфейс Swagger и ReDoc можно интегрировать в приложение несколькими способами. Редакторы, такие как Visual Studio и VS 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.

Использование 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/v1, чтобы просмотреть скалярный пользовательский интерфейс.

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

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

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

Включите создание документов во время сборки, задав следующие свойства в файле приложения .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)

Узнайте, как использовать сгенерированный документ OpenAPI в минимальном API в .NET 6, 7 или 8, смотрите в обзоре Swagger и NSwag.