OpenAPI, версионирование и развёртывание
Создавайте документацию Swagger/OpenAPI, версионируйте API и развёртывайте минимальный API в Azure App Service или контейнерах.
«OpenAPI, версионирование и развёртывание» — бесплатный урок C# Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения C# Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс C# Academy содержит 4 уроков всего.
OpenAPI в минимальных API
OpenAPI (ранее Swagger) создаёт интерактивную документацию API. В .NET 9 встроен AddOpenApi(). Для более ранних версий используйте Swashbuckle.AspNetCore.
Добавление Swagger с помощью Swashbuckle
Установите Swashbuckle, настройте его в службах и добавьте промежуточное ПО для предоставления спецификации и интерфейса Swagger.
// dotnet add package Swashbuckle.AspNetCore
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opt =>
opt.SwaggerDoc("v1", new() { Title = "Products API", Version = "v1" }));
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}Аннотирование конечных точек для OpenAPI
Используйте Produces, ProducesProblem, WithSummary и WithDescription, чтобы обогатить создаваемую спецификацию OpenAPI.
app.MapGet("/products/{id}", GetProduct)
.WithName("GetProductById")
.WithSummary("Get a product by ID")
.WithDescription("Returns the product matching the given numeric ID.")
.Produces<ProductDto>(200)
.Produces<ProblemDetails>(404)
.WithTags("Products");Версионирование API с помощью групп маршрутов
Простая стратегия версионирования использует группы маршрутов с префиксом версии. Для базового версионирования дополнительный пакет не нужен.
var v1 = app.MapGroup("/api/v1").WithTags("v1");
var v2 = app.MapGroup("/api/v2").WithTags("v2");
v1.MapGet("/products", GetProductsV1);
v2.MapGet("/products", GetProductsV2); // different DTO shape
// Clients use /api/v1/products or /api/v2/productsAsp.Versioning для версионирования через заголовок или строку запроса
Пакет Asp.Versioning.Http добавляет в минимальные API версионирование через строку запроса, заголовок и сегмент URL, а также полную интеграцию с OpenAPI.
// dotnet add package Asp.Versioning.Http
builder.Services.AddApiVersioning(opt =>
{
opt.DefaultApiVersion = new ApiVersion(1, 0);
opt.AssumeDefaultVersionWhenUnspecified = true;
opt.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});
// /products?api-version=2.0
app.MapGet("/products", GetProducts)
.HasApiVersion(2, 0);Создание отдельной спецификации для каждой версии
Настройте Swashbuckle для создания отдельных документов OpenAPI для каждой версии, чтобы потребители видели только конечные точки, относящиеся к их версии.
builder.Services.AddSwaggerGen(opt =>
{
opt.SwaggerDoc("v1", new() { Title = "API", Version = "v1" });
opt.SwaggerDoc("v2", new() { Title = "API", Version = "v2" });
});
app.UseSwaggerUI(opt =>
{
opt.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
opt.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});Публикация автономного двоичного файла
Опубликуйте минимальный API как автономный единый двоичный файл — целевой машине не потребуется среда выполнения .NET.
# Publish for Linux x64 as self-contained
dotnet publish -c Release -r linux-x64 --self-contained true
# Run the output binary
./bin/Release/net9.0/linux-x64/publish/MyApi
# Optionally single-file:
# dotnet publish -c Release -r linux-x64 -p:PublishSingleFile=trueКонтейнеризация с помощью Docker
Упакуйте API в образ Docker с использованием официальных базовых образов .NET. Многоэтапный Dockerfile позволяет уменьшить размер конечного образа.
# Dockerfile (multi-stage)
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApi.dll"]
# Build and run
# docker build -t my-api .
# docker run -p 8080:8080 my-apiРазвёртывание в Azure App Service
Разверните приложение непосредственно в Azure App Service из CLI. Сервис выполняет масштабирование и управляет сертификатами и пользовательскими доменами.
# Publish to folder first
dotnet publish -c Release -o ./publish
# Deploy to Azure App Service
az webapp up \
--name my-products-api \
--resource-group myRG \
--runtime DOTNETCORE:9.0 \
--sku B1
# View logs
az webapp log tail --name my-products-api --resource-group myRGПроверки работоспособности
Добавьте конечные точки проверки работоспособности, чтобы оркестраторы (Kubernetes, Azure) могли убедиться, что ваш API работает и готов обслуживать трафик.
builder.Services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>()
.AddUrlGroup(new Uri("https://api.external.com/ping"), "external");
app.MapHealthChecks("/health");
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = hc => hc.Tags.Contains("ready")
});Практический пример: контрольный список для промышленной эксплуатации
API для промышленной эксплуатации должен включать эти настройки для корректности, наблюдаемости и безопасности.
// builder configuration
builder.Services.AddProblemDetails();
builder.Services.AddHealthChecks();
builder.Services.AddRateLimiter(...);
builder.Services.AddOutputCache();
// app pipeline
app.UseHttpsRedirection();
app.UseExceptionHandler();
app.UseRateLimiter();
app.UseOutputCache();
app.UseAuthentication();
app.UseAuthorization();
app.MapHealthChecks("/health");
// ... your endpoints
app.Run();Быстрая проверка
Какой метод делает метаданные конечной точки (Produces, WithSummary и т. д.) видимыми для инструментов OpenAPI в минимальных API?
Итоги: OpenAPI, версионирование и развёртывание
Основные выводы:
- AddEndpointsApiExplorer + Swashbuckle = интерфейс Swagger для минимальных API
- Используйте Produces, WithSummary и WithTags для подробной документации OpenAPI
- Простое версионирование выполняется через группы маршрутов; Asp.Versioning подходит для расширенных сценариев
- Публикуйте автономное приложение или образ Docker для гибкого развёртывания
- Добавляйте проверки работоспособности для проб готовности Kubernetes/Azure
Часто задаваемые вопросы
Урок «OpenAPI, версионирование и развёртывание» бесплатный?
Да — полный текст урока «OpenAPI, версионирование и развёртывание» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс C# Academy, подпишись на CoddyKit PRO. Курс C# Academy содержит 4 уроков всего.
Чему я научусь в уроке «OpenAPI, версионирование и развёртывание»?
Создавайте документацию Swagger/OpenAPI, версионируйте API и развёртывайте минимальный API в Azure App Service или контейнерах. Ты практикуешь C# Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать C# Academy?
Предыдущий опыт не требуется. C# Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.
Сколько времени занимает урок «OpenAPI, версионирование и развёртывание»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке C# Academy?
Да. Каждый урок C# Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Создание первого минимального API
- Группы маршрутов, параметры и проверка
- Промежуточное ПО и фильтры в минимальных API
- OpenAPI, версионирование и развёртывание