Как использовать OpenAPI в ASP.NET Core

В ASP.NET Core 6 представлена ​​упрощенная модель размещения, которая позволяет нам создавать облегченные API с минимальными зависимостями. Эти минимальные API-проекты упрощают быстрое развертывание и запуск нашего приложения за счет написания меньшего количества шаблонного кода. ASP.NET Core 7 дополнительно улучшил минимальные API, добавив поддержку фильтров.

Всякий раз, когда вы работаете с API-интерфейсами, включая минимальные API-интерфейсы, вам часто требуется документировать свои конечные точки. К счастью, ASP.NET Core предоставляет встроенную поддержку спецификации OpenAPI, так что вы можете воспользоваться преимуществами OpenAPI и пользовательского интерфейса Swagger для создания хорошей документации для всех ваших API.

Цель этого поста — дать вам фору в этом. Чтобы использовать примеры кода, представленные в этой статье, в вашей системе должна быть установлена ​​Visual Studio 2022. Если у вас еще нет копии, вы можете скачать Visual Studio 2022 здесь.

Создайте минимальный проект веб-API в Visual Studio 2022.

Прежде всего, давайте создадим проект ASP.NET Core в Visual Studio 2022. Выполните следующие действия:

1. Запустите интегрированную среду разработки Visual Studio 2022.
2. Нажмите «Создать новый проект».
3. В окне «Создать новый проект» выберите «ASP.NET Core Web API» из списка отображаемых шаблонов.
4. Нажмите “Далее.
5. В окне «Настроить новый проект» укажите имя и расположение нового проекта.
6. При желании установите флажок «Поместить решение и проект в один каталог», в зависимости от ваших предпочтений.
7. Нажмите “Далее.
8. В показанном ниже окне «Дополнительная информация» снимите флажок «Использовать контроллеры…», поскольку в этом примере мы будем использовать минимальное количество API. Оставьте для параметра «Тип аутентификации» значение «Нет» (по умолчанию). Установите флажки «Настроить для HTTPS» и «Включить поддержку Open API». Наконец, убедитесь, что флажок «Включить Docker» не установлен, так как мы не будем использовать Docker здесь. (См. рисунок 1 ниже.)
9. Щелкните Создать.

IDG

Мы будем использовать этот проект веб-API ASP.NET Core 7, чтобы использовать OpenAPI для документирования минимальных конечных точек API в разделах ниже.

Что такое спецификация OpenAPI?

Ранее известная как спецификация Swagger, спецификация OpenAPI определяет стандартный, машиночитаемый, независимый от языка программирования язык описания интерфейса (IDL) для API. Это независимый от языка стандарт для описания HTTP API. Стандарт поддерживается комбинацией встроенных API и библиотек с открытым исходным кодом.

Три наиболее важных аспекта интеграции OpenAPI в приложение:

1. Создание информации о конечных точках приложения.
2. Объединение данных в формат, совместимый со стандартом OpenAPI.
3. Предоставление созданной схемы OpenAPI через графический интерфейс пользователя или сериализованный файл.

Поскольку мы включили поддержку OpenAPI при создании проекта веб-API ASP.NET Core 7, пакет Swashbuckle.AspNetCore будет добавлен в проект автоматически. Swashbuckle — это проект с открытым исходным кодом, который позволяет создавать документацию Swagger.

Обратите внимание, что вы всегда можете добавить пакет NuGet Swashbuckle.AspNetCore в другие проекты вручную.

Создайте простую минимальную конечную точку API в ASP.NET Core.

Когда вы создаете новый проект веб-API ASP.NET Core в Visual Studio, контроллер по умолчанию (с именем WeatherForecast) и класс модели создаются автоматически. Поскольку здесь мы используем минимальные API, эти файлы создаваться не будут.

Вместо этого в файле Program.cs будет создана конечная точка HTTP GET по умолчанию. Теперь замените сгенерированный по умолчанию код конечной точки HTTP GET следующим кодом.

app.MapGet("https://www.infoworld.com/", () => "Hello World!")
.WithName("Welcome")
.WithOpenApi();

Когда вы запустите приложение, вы сможете увидеть пользовательский интерфейс Swagger в своем веб-браузере, как показано на рисунке 2.

IDG

Настройте Swagger в минимальном API в ASP.NET Core

Фрагмент кода ниже иллюстрирует, как можно настроить промежуточное ПО Swagger для добавления метаданных в документ API.

builder.Services.AddSwaggerGen(setup => setup.SwaggerDoc("v1", new OpenApiInfo()
{
    Description = "This is a simple implementation of a Minimal Api in Asp.Net 7 Core",
    Title = "Demo Api",
    Version = "v1",
    Contact = new OpenApiContact()
    {
        Name = "Joydip Kanjilal",
        Url = new Uri("https://joydipkanjilal.com")
    }
}));

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

IDG

Создайте класс модели

Теперь давайте конкретизируем наше минимальное приложение-пример API. Сначала создайте класс модели, используя следующий код.

public class Author
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
}

Создать и реализовать интерфейс

Затем создайте интерфейс с именем IAuthorRepository и введите следующий код.

public interface IAuthorRepository
{
    Author GetById(int id);
    void Create(Author entity);
    void Delete(Author entity);
    void Update(Author entity);
}

Теперь создайте еще один класс с именем AuthorRepository и введите следующий код.

public class AuthorRepository : IAuthorRepository
{
    void IAuthorRepository.Create(Author entity)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Delete(Author entity)
    {
        throw new NotImplementedException();
    }
    Author IAuthorRepository.GetById(int id)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Update(Author entity)
    {
        throw new NotImplementedException();
    }
}

Обратите внимание, что ни один из методов класса AuthorRepository не реализован. Мы будем использовать эту базовую реализацию только для того, чтобы увидеть, как мы можем работать с OpenAPI в минимальных приложениях API.

Создайте минимальную конечную точку API

Наконец, удалите конечную точку, которую мы создали ранее, так как она нам больше не понадобится. Вместо этого добавьте следующий фрагмент кода в файл Program.cs, чтобы создать четыре новые конечные точки.

app.MapGet("/authors/{id}", async ([FromServices] Author entity, int id) =>
{
    return Results.Ok();
});
app.MapPost("/authors", async ([FromServices] Author entity) =>
{
    return Results.Ok();
});
app.MapPut("/authors/{id}", async ([FromServices] int id, Author entityToUpdate) =>
{
    return Results.Ok();
});
app.MapDelete("/authors/{id}", async ([FromServices] int id) =>
{
    return Results.Ok();
});

Когда вы запускаете приложение, вы должны увидеть эти конечные точки, отображаемые в пользовательском интерфейсе Swagger, как показано на рис. 4.

IDG

Полный минимальный пример API в ASP.NET Core

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

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddSwaggerGen(setup => setup.SwaggerDoc("v1", new OpenApiInfo()
{
    Description = "This is a simple implementation of a Minimal Api in Asp.Net 7 Core",
    Title = "Demo Api",
    Version = "v1",
    Contact = new OpenApiContact()
    {
        Name = "Joydip Kanjilal",
        Url = new Uri("https://joydipkanjilal.com")
    }
}));
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.MapGet("/authors/{id}", async ([FromServices] Author entity, int id) =>
{
    return Results.Ok();
});
app.MapPost("/authors", async ([FromServices] Author entity) =>
{
    return Results.Ok();
});
app.MapPut("/authors/{id}", async ([FromServices] int id, Author entityToUpdate) =>
{
    return Results.Ok();
});
app.MapDelete("/authors/{id}", async ([FromServices] int id) =>
{
    return Results.Ok();
});
app.Run();
public class Author
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
}
public interface IAuthorRepository
{
    Author GetById(int id);
    void Create(Author entity);
    void Delete(Author entity);
    void Update(Author entity);
}
public class AuthorRepository : IAuthorRepository
{
    void IAuthorRepository.Create(Author entity)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Delete(Author entity)
    {
        throw new NotImplementedException();
    }
    Author IAuthorRepository.GetById(int id)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Update(Author entity)
    {
        throw new NotImplementedException();
    }
}

Включив поддержку OpenAPI в своих проектах веб-API при их создании, вы можете настроить ASP.NET Core на автоматическое документирование конечных точек HTTP и просмотреть эту информацию через пользовательский интерфейс Swagger. Обратите внимание, что вы можете настраивать пользовательский интерфейс Swagger с помощью каскадных таблиц стилей, отображать значения перечисления в виде строковых значений и создавать разные документы Swagger для разных версий вашего API.