C# Academy · Урок

Генерация документов OpenAPI

Создавайте спецификации API в машиночитаемом формате.

«Генерация документов OpenAPI» — бесплатный урок C# Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения C# Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс C# Academy содержит 4 уроков всего.

Что такое OpenAPI

OpenAPI — это стандартное машиночитаемое описание HTTP API. На его основе можно создавать документацию, клиентские SDK и инструменты тестирования.

.NET 9 включает встроенную генерацию документов OpenAPI, которая во многих приложениях заменяет прежнюю зависимость Swashbuckle.

// OpenAPI document = JSON describing paths, schemas, params

Пакет Microsoft.AspNetCore.OpenApi

Встроенная поддержка размещена в Microsoft.AspNetCore.OpenApi. В шаблонах .NET 9 этот пакет уже подключён.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Зарегистрируйте генератор документов с помощью AddOpenApi в конфигурации служб.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi предоставляет сгенерированный документ по конечной точке. По умолчанию он доступен по адресу /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Только для среды разработки

Обычно документ предоставляют только в среде разработки, чтобы не раскрывать набор возможностей API в рабочей среде.

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

Описание конечных точек

Метаданные OpenAPI дополняются из вашего кода. Используйте WithSummary, WithDescription и WithTags у конечных точек минимального API.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Документирование ответов

Объявите типы ответов и коды состояния, чтобы документ точно перечислял их.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Преобразователи документов

Настройте весь документ — заголовок, версию и серверы — с помощью преобразователя документа, переданного в AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Преобразователи операций

Преобразователь операции изменяет отдельные операции — например, добавляет общий параметр заголовка каждой конечной точке.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Добавление пользовательского интерфейса

Встроенный генератор создаёт документ JSON, но не пользовательский интерфейс. Дополните его средством просмотра, например Scalar или Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Генерация во время сборки

Вы можете создать файл OpenAPI во время сборки (без запущенного сервера) с помощью инструментария Microsoft.Extensions.ApiDescription.Server — это удобно для генерации клиентов в системе непрерывной интеграции.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Быстрая проверка

Проверьте основные сведения об OpenAPI в .NET 9.

Итоги

Вы сгенерировали документы OpenAPI:

AddOpenApi() регистрирует генератор; MapOpenApi() предоставляет JSON.
Дополняйте конечные точки с помощью WithSummary, Produces и тегов.
Преобразователи документов и операций настраивают результат.
Дополните их Scalar или Swagger UI для интерактивного просмотра.

Далее: документирование версионированных API.

Часто задаваемые вопросы

Урок «Генерация документов OpenAPI» бесплатный?

Да — полный текст урока «Генерация документов OpenAPI» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс C# Academy, подпишись на CoddyKit PRO. Курс C# Academy содержит 4 уроков всего.

Чему я научусь в уроке «Генерация документов OpenAPI»?

Создавайте спецификации API в машиночитаемом формате. Ты практикуешь C# Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать C# Academy?

Предыдущий опыт не требуется. C# Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Генерация документов OpenAPI»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке C# Academy?

Да. Каждый урок C# Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к C# Academy