OpenAPI, 버전 관리와 배포

미니멀 API의 OpenAPI

Swashbuckle로 스웨거 추가하기

// 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를 위한 엔드포인트 주석 지정

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/products

헤더 및 쿼리 버전 관리를 위한 Asp.Versioning

// 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);

버전별 별도 사양 생성하기

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");
});

자체 포함 바이너리 배포

# 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

도커로 컨테이너화하기

# 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

애저 앱 서비스에 배포하기

# 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

상태 검사

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")
});

실전: 프로덕션 체크리스트

// 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();

확인 문제

복습: OpenAPI, 버전 관리 및 배포