Использование документов 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, зарегистрированный ранее.
- Чтобы ограничить раскрытие информации и уязвимость безопасности, включите только пользовательский интерфейс Swagger в средах разработки.
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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "v1");
});
}
app.MapGet("/", () => "Hello world!");
app.Run();
Использование 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference();
}
app.MapGet("/", () => "Hello world!");
app.Run();
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)
ASP.NET Core