C# Academy · Урок

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

Предоставляйте документацию для нескольких версий API.

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

Отдельный документ для каждой версии

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

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

Поставщик описаний версий API

Asp.Versioning предоставляет IApiVersionDescriptionProvider, который перечисляет все обнаруженные версии API. Переберите его, чтобы зарегистрировать отдельный документ для каждой версии.

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

Регистрация документа для каждой версии

Вызовите AddOpenApi один раз для каждой группы версий, назвав каждый документ в соответствии с группой.

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Отбор конечных точек для нужного документа

Используйте преобразователь документа или предикат ShouldInclude, чтобы каждый документ содержал только конечные точки своей версии, сопоставленные по имени группы.

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

Сопоставление документов

MapOpenApi с шаблоном по умолчанию предоставляет каждый именованный документ по адресу /openapi/{documentName}.json.

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

Настройка сведений для каждого документа

Задайте для документа каждой версии собственные заголовок и номер версии с помощью преобразователя, чтобы документация содержала всю необходимую информацию.

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

Пометка устаревших версий в документации

Если версия устарела, укажите это в описании её документа, чтобы пользователи видели предупреждение в интерфейсе.

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

Подстановка версии в URL

SubstituteApiVersionInUrl = true заменяет маркер маршрута {version:apiVersion} конкретной версией (например, v1) в документе, поэтому пути выглядят понятнее.

// Without: /api/v{version}/products
// With:    /api/v1/products

Вкладка интерфейса для каждой версии

Большинство средств просмотра могут показывать раскрывающийся список всех документов. Настройте интерфейс на JSON-файл каждой версии.

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

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

Поскольку в v2 структуры объектов передачи данных могут измениться, задайте для каждой версии собственные типы объектов передачи данных. OpenAPI автоматически отобразит отдельные схемы для каждого документа.

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

Объединение всего

Полный процесс: настройте версионирование и обозреватель API, зарегистрируйте по одному документу OpenApi для каждой версии с фильтром, сопоставьте их и настройте интерфейс на каждый документ.

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

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

Проверьте, как создаётся документация для версий.

Итоги

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

Зарегистрируйте по одному именованному документу OpenAPI для каждой версии с помощью AddOpenApi("vN").
IApiVersionDescriptionProvider перечисляет версии; ShouldInclude отбирает конечные точки.
SubstituteApiVersionInUrl отображает пути с конкретными версиями.
Настройте интерфейс на каждый документ, чтобы получить представление для отдельной версии.

На этом курс по версионированию и OpenAPI завершён.

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

Урок «Документирование версионируемых API» бесплатный?

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

Чему я научусь в уроке «Документирование версионируемых API»?

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

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

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

Сколько времени занимает урок «Документирование версионируемых API»?

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

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

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

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

← Назад к C# Academy