자습서: ASP.NET Core를 사용하여 최소 API 만들기

웨이드 피켓과 톰 다이크스트라

최소 API는 최소한의 종속성을 사용하여 HTTP API를 만들도록 설계되었습니다. ASP.NET Core에 최소 파일, 기능 및 종속성만 포함하려는 마이크로 서비스 및 앱에 이상적입니다.

이 자습서에서는 ASP.NET Core를 사용하여 최소 API를 빌드하는 기본 사항을 설명합니다. ASP.NET Core에서 API를 만드는 또 다른 방법은 컨트롤러를 사용하는 것입니다. 최소 API와 컨트롤러 기반 API 중에서 선택하는 방법에 대한 도움말은 API 개요를 참조하세요. 더 많은 기능이 포함된 컨트롤러를 기반으로 API 프로젝트를 만드는 방법에 대한 자습서는 웹 API 만들기를 참조하세요.

Overview

이 자습서에서는 다음 API를 만듭니다.

API	Description	요청 메시지 본문	응답 본문
GET /todoitems	할 일 항목 모두 가져오기	None	할 일 항목의 배열
GET /todoitems/complete	완성된 할 일 항목 가져오기	None	할 일 항목의 배열
GET /todoitems/{id}	ID로 항목 가져오기	None	할 일 항목
POST /todoitems	새 항목 추가	할 일 항목	할 일 항목
PUT /todoitems/{id}	기존 항목 업데이트	할 일 항목	None
PATCH /todoitems/{id}	항목 부분 업데이트	부분 할 일 항목	None
DELETE /todoitems/{id}	항목 삭제	None	None

Prerequisites

Visual Studio

• ASP.NET 및 웹 개발 워크로드가 있는 최신 버전의 Visual Studio입니다.

  

Visual Studio Code

• Visual Studio Code
• Visual Studio Code용 C# 개발 키트
• .NET 10.0 SDK

macOS, Linux 또는 Windows에서 Visual Studio Code 지침을 따를 수 있습니다. Visual Studio Code 이외의 IDE(통합 개발 환경)를 사용하는 경우 변경이 필요할 수 있습니다.

API 프로젝트 만들기

Visual Studio

• 2026년 Visual Studio 시작하고 새 프로젝트 만들기 선택합니다.

• 새 프로젝트 만들기 대화 상자에서 다음을 수행합니다.

  • ASP.NET Core Web API 프로젝트 형식을 선택하고 다음을 선택합니다.
  • 프로젝트 이름을 TodoApi로 지정하고 다음을 선택합니다.

• 추가 정보 대화 상자에서 다음을 수행합니다.

  • Framework가 .NET 10.0(장기 지원)인지 확인합니다.
  • OpenAPI 지원 사용 확인란이 선택되어 있는지 확인합니다.
  • 컨트롤러 사용 확인란이 선택되어 있지 않은지 확인합니다. 컨트롤러 기반 프로젝트가 아닌 이 자습서에 필요한 최소 API 프로젝트를 만들려면 이 설정을 선택 취소합니다.
  • Create를 선택합니다.

  

Visual Studio Code

• Visual Studio Code 시작하고 보기를 선택한 다음 터미널을 선택하여 통합 터미널을 엽니다.
• 디렉터리(cd)를 프로젝트를 만들 폴더로 변경합니다.
• 다음 명령을 실행합니다.

  dotnet new webapi -o TodoApi
  code -r TodoApi

• 대화 상자에서 작성자를 신뢰할지 묻는 메시지가 표시되면 예를 선택합니다.

• 프로젝트에 필수 자산을 추가하려는지 묻는 대화 상자가 나타나면 예를 선택합니다.

  위의 명령은 새 웹 최소 API 프로젝트를 만들고 Visual Studio Code에서 엽니다.

코드 검사

템플릿에서 생성된 파일에는 Program.cs 다음 코드가 포함되어 있습니다.

Visual Studio

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Visual Studio Code

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

앞의 코드가 하는 역할은 다음과 같습니다.

• 미리 구성된 기본값을 사용하여 WebApplicationBuilder 및 WebApplication을 만듭니다.
• builder.Services.AddOpenApi()를 사용하여 기본 제공 OpenAPI 문서 생성기를 등록합니다.
• 개발 환경에서만 /openapi/v1.json를 사용하여 생성된 OpenAPI 문서를 app.MapOpenApi()에 매핑합니다.
• 임의로 생성된 5개의 레코드를 반환하는 샘플 GET /weatherforecast 엔드포인트를 WeatherForecast 정의합니다.

이 자습서에서는 WeatherForecast를 항목을 만들고, 읽고, 업데이트하고, 삭제하는 엔드포인트와 모델 및 데이터베이스를 기반으로 하는 새 Todo 샘플로 바꿉니다.

NuGet 패키지 추가

이 자습서에서 사용되는 데이터베이스를 지원하는 NuGet 패키지를 추가합니다.

Visual Studio

• 도구 메뉴에서 NuGet 패키지 관리자 > 솔루션용 NuGet 패키지 관리를 선택합니다.
• 찾아보기 탭을 선택합니다.
• 검색 상자에 Microsoft.EntityFrameworkCore.InMemory를 입력한 다음 Microsoft.EntityFrameworkCore.InMemory를 선택합니다.
• 오른쪽 창에서 프로젝트 확인란을 선택하고 설치를 선택합니다.

Visual Studio Code

• 다음 명령을 실행합니다.

  dotnet add package Microsoft.EntityFrameworkCore.InMemory

모델 및 데이터베이스 컨텍스트 클래스

• 프로젝트 폴더에서 다음 코드가 포함된 Todo.cs라는 파일을 만듭니다.

public class Todo
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
    public string? Secret { get; set; }
}

앞의 코드는 이 앱에 대한 모델을 만듭니다. 모델은 앱에서 관리하는 데이터를 나타내는 일련의 클래스입니다.

이 Secret 속성은 일반적인 실제 필요성을 보여주기 위해 포함됩니다. 앱이 내부적으로 저장하고 사용하는 데이터(예: 항목을 소유한 사용자의 ID)는 클라이언트가 보거나 설정하지 않도록 합니다. 이 자습서 뒷부분의 초과 게시 방지 단계에서는 DTO(데이터 전송 객체)를 사용하여 Secret와 같은 필드가 API의 입력 및 응답에 포함되지 않도록 합니다.

• 다음 코드를 사용하여 TodoDb.cs라는 파일을 만듭니다.

using Microsoft.EntityFrameworkCore;

class TodoDb : DbContext
{
    public TodoDb(DbContextOptions<TodoDb> options)
        : base(options) { }

    public DbSet<Todo> Todos => Set<Todo>();
}

앞의 코드는 데이터 모델에 대한 Entity Framework 기능을 조정하는 기본 클래스인 데이터베이스 컨텍스트를 정의합니다. 이 클래스는 Microsoft.EntityFrameworkCore.DbContext 클래스에서 파생됩니다.

앱은 라는 TodoList메모리 내 데이터베이스를 사용합니다. 데이터베이스는 나중에 Program.cs에서 builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));을 사용하여 등록되며, 여기서 문자열 "TodoList"는 데이터베이스 이름입니다. 데이터는 메모리에 저장되므로 앱이 다시 시작될 때마다 다시 설정됩니다.

WeatherForecast 샘플을 Todo API로 바꾸기

템플릿은 webapi에 샘플 GET /weatherforecast 엔드포인트를 추가하고 파일 맨 아래에 Program.cs 레코드를 추가합니다. 샘플은 템플릿이 제대로 작동함을 보여 주기 위한 자리 표시자일 뿐이므로, 둘 다 다음 섹션에 설명된 Todo 엔드포인트로 교체하세요.

• 모든 코드를 Program.cs 다음으로 바꿉다. WeatherForecast 샘플 엔드포인트와 레코드가 제거되고 Todo 엔드포인트가 해당 위치를 차지합니다.

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

붙여넣은 코드에는 API를 테스트하기 위한 브라우저 UI를 추가하는 using Scalar.AspNetCore; 및 app.MapScalarApiReference();도 포함되어 있습니다. 이 자습서의 뒷부분에 있는 OpenAPI 문서를 보려면 브라우저 UI 추가에서 이러한 줄에 대한 스칼라 패키지를 구성합니다. 이 프로젝트는 그때까지 빌드되지 않습니다.

템플릿이 추가하는 OpenAPI 줄(builder.Services.AddOpenApi() 및 app.MapOpenApi())은 그대로 유지됩니다. 이제 샘플 날씨 엔드포인트 대신 Todo 엔드포인트를 설명합니다.

강조 표시된 다음 코드는 DI(종속성 주입) 컨테이너에 앱의 서비스를 등록합니다. 데이터베이스 컨텍스트(AddDbContext) 및 OpenAPI 문서 생성기(AddOpenApi).

Visual Studio

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

Visual Studio Code

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

DI 컨테이너는 데이터베이스 컨텍스트 및 기타 서비스에 대한 액세스를 제공합니다.

Visual Studio

이 자습서에서는 엔드포인트 탐색기 및 .http 파일을 사용하여 API를 테스트합니다.

Visual Studio Code

브라우저 UI를 추가하여 OpenAPI 문서 보기

템플릿에서 OpenAPI 문서를 이미 생성하고 있습니다 /openapi/v1.json. 브라우저에서 API를 탐색하고 테스트하려면 해당 문서를 사용하는 UI를 추가합니다. 이 자습서에서는 스칼라를 사용합니다.

UI를 제공하는 미들웨어를 제공하는 Scalar.AspNetCore 패키지를 추가합니다.

• 다음 명령을 실행합니다.

  dotnet add package Scalar.AspNetCore

이 자습서에서는 Scalar가 AddOpenApi 및 MapOpenApi 호출에 의해 생성된 OpenAPI 문서를 읽는 API 참조 미들웨어에만 사용됩니다.

Program.cs에 강조 표시된 MapScalarApiReference 줄이 if (app.Environment.IsDevelopment()) 블록 내부의 app.MapOpenApi(); 줄 바로 뒤에 포함되어 있는지, 그리고 using Scalar.AspNetCore;가 파일 맨 위에 있는지 확인합니다. 이전에 Todo 코드를 붙여넣을 때 이러한 줄을 추가했습니다.

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

위의 코드는 개발에서만 스칼라 UI를 사용하도록 설정합니다. /openapi/v1.json에서 생성된 문서MapOpenApi()를 읽고, /scalar/v1에서 API 참조를 제공합니다. 파일 맨 위에 using Scalar.AspNetCore;를 반드시 추가하세요.

Note

스칼라는 OpenAPI UI에 대한 여러 옵션 중 하나입니다. NSwag.AspNetCore 또는 Swashbuckle.AspNetCore.SwaggerUi와 같은 대안은 동일한 OpenAPI 문서를 사용하며, 튜토리얼의 나머지 부분을 변경하지 않고도 Scalar 대신 사용할 수 있습니다.

데이터 게시 테스트

Program.cs에서 다음 코드는 HTTP POST 엔드포인트 /todoitems를 만들어 메모리 내 데이터베이스에 데이터를 추가합니다.

Visual Studio

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

Visual Studio Code

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

Visual Studio

• Ctrl+F5 키를 눌러 디버깅하지 않고 앱을 실행합니다. Visual Studio 웹 서버를 시작하고Kestrel 필요한 경우 개발 인증서를 신뢰합니다.

Visual Studio는 다음 대화 상자를 표시합니다.

IIS Express SSL 인증서를 신뢰하는 경우 예를 선택합니다.

다음 대화 상자가 표시됩니다.

개발 인증서를 신뢰하는 데 동의하는 경우 예를 선택합니다.

Firefox 브라우저를 신뢰하는 방법에 대한 자세한 내용은 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 인증서 오류를 참조하세요.

POST 엔드포인트를 사용하여 앱에 데이터를 추가합니다.

• 선택 보기>다른 Windows>Endpoints 탐색기.

• POST 엔드포인트를 마우스 오른쪽 단추로 클릭하고 요청 생성을 선택합니다.

  

  다음 예제와 유사한 내용이 포함된 새 파일이 프로젝트 폴더 TodoApi.http에 만들어집니다.

  @TodoApi_HostAddress = https://localhost:7031

  POST {{TodoApi_HostAddress}}/todoitems

  ###

• 첫 번째 줄은 모든 엔드포인트에 사용되는 변수를 만듭니다.

• 다음 줄은 POST 요청을 정의합니다.

• 삼중 해시 태그(###) 줄은 요청 구분 기호입니다. 이는 다른 요청에 대한 것입니다.

• POST 요청에는 헤더와 본문이 필요합니다. 요청의 해당 부분을 정의하려면 POST 요청 줄 바로 다음에 다음 줄을 추가합니다.

  Content-Type: application/json

  {
    "name":"walk dog",
    "isComplete":true
  }

앞의 코드는 Content-Type 헤더와 JSON 요청 본문을 추가합니다. 이제 TodoApi.http 파일은 다음 예제와 비슷하게 보이지만, 사용자 본인의 포트 번호를 사용해야 합니다.

  @TodoApi_HostAddress = https://localhost:7057

  POST {{TodoApi_HostAddress}}/todoitems
  Content-Type: application/json

  {
    "name":"walk dog",
    "isComplete":true
  }

  ###

• 요청 줄 위에 POST 있는 요청 보내기 링크를 선택합니다.

  

  POST 요청이 앱으로 전송되고 응답 창에 응답이 표시됩니다.

  

Visual Studio Code

• 다음 명령을 실행하여 HTTPS 개발 인증서를 신뢰합니다.

  dotnet dev-certs https --trust
  

  위의 명령은 이전에 인증서를 신뢰할 수 없었던 경우 다음 대화 상자를 표시합니다.

  

• 개발 인증서를 신뢰하는 데 동의하는 경우 예를 선택합니다.

  자세한 내용은 SSL 적용 문서의 ASP.NET Core HTTPS 개발 인증서 신뢰 섹션을 참조하세요.

Firefox 브라우저를 신뢰하는 방법에 대한 자세한 내용은 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 인증서 오류를 참조하세요.

• Visual Studio Code에서 Ctrl+(Windows) 또는 컨트롤+(macOS)를 눌러 디버깅 없이 앱을 실행합니다.

• 디버거를 선택하라는 메시지가 표시됩니다. C#선택합니다.

• 시작 구성을 선택하라는 메시지가 표시됩니다. C#:TodoApi [기본 구성] TodoApi 선택

  

앱은 TodoApi 임의로 할당된 로컬 포트에서 시작되고 수신 대기합니다. 터미널 패널에서 URL 및 포트를 가져올 줄을 찾 Now listening on: 습니다. 예를 들면 다음과 같습니다.

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5090

이 예제에서 TodoApi 앱은 http://localhost:5090에서 수신 대기하고 있으므로 포트는 5090입니다. 포트 번호가 다를 수 있습니다.

• 기본 브라우저에서 앱을 열려면 Ctrl(Windows) 또는 Cmd(macOS)를 누Now listening on: 패널의 줄에서 URL을 선택합니다. 브라우저가 앱의 루트 http://localhost:{port}에서 열립니다.

• 브라우저 주소 표시줄에서 URL 끝에 /scalar/v1를 추가하면 Scalar가 생성한 API 참조 페이지가 표시됩니다. 예를 들어 http://localhost:5090/scalar/v1입니다.

• 스칼라 페이지에서 POST/todoitems 작업을 선택한 다음, 테스트 요청을 선택합니다.

• 요청 본문에서 선택 사항을 id지정하지 않고 to-do 항목에 대한 JSON을 입력합니다.

  {
    "name":"walk dog",
    "isComplete":true
  }

• 보내기를 선택합니다.

스칼라 UI는 상태 코드 및 응답 본문을 포함하여 응답을 표시합니다. 응답 본문은 다음을 보여 줍니다.

• id이 1로 설정됩니다.
• 요청이 성공적으로 처리되고 새 리소스가 생성되었음을 나타내는 201 HTTP 상태 코드가 반환됩니다.

GET 엔드포인트 검사

사용자의 Program.cs에는 MapGet로 정의된 여러 GET 엔드포인트가 포함되어 있습니다.

API	Description	요청 메시지 본문	응답 본문
GET /todoitems	할 일 항목 모두 가져오기	None	할 일 항목의 배열
GET /todoitems/complete	완성된 모든 할 일 항목 가져오기	None	할 일 항목의 배열
GET /todoitems/{id}	ID로 항목 가져오기	None	할 일 항목

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

GET 엔드포인트 테스트

Visual Studio

브라우저에서 엔드포인트를 GET 호출하거나 엔드포인트 탐색기를 사용하여 앱을 테스트합니다. 다음 단계는 엔드포인트 탐색기를 위한 것입니다.

• 엔드포인트 탐색기에서 첫 번째 GET 엔드포인트를 마우스 오른쪽 단추로 클릭하고 요청 생성을 선택합니다.

  다음 콘텐츠가 TodoApi.http 파일에 추가됩니다.

  GET {{TodoApi_HostAddress}}/todoitems

  ###

• 새로운 요청 줄 위에 있는 요청 보내기 링크를 선택합니다.

  GET 요청이 앱으로 전송되고 응답 창에 응답이 표시됩니다.

• 응답 본문은 다음 JSON과 유사합니다.

  [
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true,
      "secret": null
    }
  ]

• 엔드포인트 탐색기에서 GET 엔드포인트를 마우스 오른쪽 버튼으로 클릭하고 /todoitems/{id}을 선택하세요. 다음 콘텐츠가 TodoApi.http 파일에 추가됩니다.

  GET {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• {id}를 1로 교체합니다.

• 새 GET 요청 줄 위에 있는 요청 보내기 링크를 선택합니다.

  GET 요청이 앱으로 전송되고 응답 창에 응답이 표시됩니다.

• 응답 본문은 다음 JSON과 유사합니다.

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }

Visual Studio Code

브라우저 또는 스칼라 UI에서 엔드포인트를 호출하여 앱을 테스트합니다.

• 스칼라 UI에서 GET /todoitems를 선택한 다음, 테스트 요청>보내기를 선택합니다.

• 다른 방법으로, 브라우저에서 URI를 입력하여 http://localhost:{port}/todoitems를 호출하세요. http://localhost:7032/todoitems을 예로 들 수 있습니다.

GET /todoitems를 호출하면 다음과 비슷한 응답이 생성됩니다.

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }
]

• 스칼라에서 GET /todoitems/{id} 를 호출하여 특정 ID에서 데이터를 반환합니다.

  • GET /todoitems/{id}를 선택한 다음, 테스트 요청을 선택합니다.
  • ID 필드를 설정하고 1를 선택합니다.

• 또는 URI를 입력하여 브라우저에서 http://localhost:{port}/todoitems/1를 호출합니다. http://localhost:7032/todoitems/1을 예로 들 수 있습니다.

• 응답은 다음과 비슷합니다.

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true,
    "secret": null
  }

이 앱은 메모리 내 데이터베이스를 사용합니다. 앱을 다시 시작하면 데이터가 유실됩니다. GET /todoitems는 빈 배열([])을 반환하고, GET /todoitems/{id}는 404 Not Found를 반환합니다. 앱을 다시 채워보려면 데이터를 앱에 게시 하고 GET 요청을 다시 시도합니다.

반환 값

ASP.NET Core는 자동으로 JSON에 개체를 직렬화하고 JSON을 응답 메시지의 본문에 기록합니다. 이 반환 형식의 응답 코드는 200 OK이며 처리되지 않은 예외가 없다고 가정합니다. 처리되지 않은 예외는 5xx 오류로 변환됩니다.

반환 형식은 다양한 HTTP 상태 코드를 나타낼 수 있습니다. 예를 들어 GET /todoitems/{id}은 두 가지 상태 값을 반환할 수 있습니다.

• 요청된 ID와 일치하는 항목이 없는 경우 메서드에서 404 상태NotFound 오류 코드를 반환합니다.
• 그렇지 않으면 메서드가 JSON 응답 본문에서 200을 반환합니다. item을 반환하면 HTTP 200 응답이 발생합니다.

PUT 엔드포인트 검사

샘플 앱은 MapPut을 사용하여 단일 PUT 엔드포인트를 구현합니다.

Visual Studio

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Visual Studio Code

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

이 메서드는 HTTP PUT을 사용한다는 점을 제외하고 MapPost 메서드와 비슷합니다. 성공적인 응답은 204(콘텐츠 없음)를 반환합니다. HTTP 사양에 따라 PUT 요청의 경우 클라이언트는 변경 내용만이 아니라 전체 업데이트된 엔터티를 보내야 합니다. 부분 업데이트를 지원하려면 HTTP PATCH를 사용합니다.

PUT 엔드포인트 테스트

이 샘플에서는 앱을 시작할 때마다 초기화해야 하는 메모리 내 데이터베이스를 사용합니다. PUT 호출을 하기 전에 데이터베이스에 항목이 필요합니다. PUT을 호출하기 전에 POST를 호출하여 데이터베이스에 항목이 있는지 확인합니다.

Id = 1이 있는 Todo 항목을 업데이트하고 이름을 "feed fish"로 설정합니다.

Visual Studio

• 엔드포인트 탐색기에서 PUT 엔드포인트를 마우스 오른쪽 단추로 클릭하고 요청 생성을 선택합니다.

  다음 콘텐츠가 TodoApi.http 파일에 추가됩니다.

  PUT {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• PUT 요청 줄에서 `{id}`를 `1`로 교체하세요.

• PUT 요청 줄 바로 다음에 다음 줄을 추가합니다.

  Content-Type: application/json

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }

앞의 코드는 Content-Type 헤더와 JSON 요청 본문을 추가합니다.

• 새 PUT 요청 줄 위에 있는 요청 보내기 링크를 선택합니다.

Visual Studio Code

스칼라 UI를 사용하여 PUT 요청을 보냅니다.

• PUT /todoitems/{id}를 선택한 다음, 테스트 요청을 선택합니다.

• ID 필드를 1로 설정합니다.

• 요청 본문을 다음 JSON으로 설정합니다.

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }

• 보내기를 선택합니다.

PUT 요청이 앱으로 전송되고 응답 창에 응답이 표시됩니다. 응답 본문이 비어 있고 상태 코드는 204입니다.

PATCH 엔드포인트 만들기 및 검사

PATCH 엔드포인트를 사용하면 클라이언트가 완료 상태를 다시 보내지 않고 Todo 항목의 이름을 바꾸는 등 업데이트하려는 필드만 보낼 수 있습니다. 이 방법은 전체 항목을 대체하는 PUT 요청과 다르므로 클라이언트는 하나만 변경되더라도 모든 필드를 보내야 합니다.

다음 단계에서는 새 파일을 추가하고 파일을 수정합니다 Program.cs . 이러한 변경을 수행하기 전에 TodoApi 앱을 중지하세요. 브라우저에서 스칼라 페이지를 실행 상태로 둡니다.

Visual Studio

• 앱을 중지하려면 Visual Studio 도구 모음에서 중지 단추(빨간색 사각형)를 선택합니다.

Visual Studio Code

• 앱을 중지하려면 ShiftF5+ 누릅니다.

이 샘플에서는 앱이 시작될 때마다 초기화해야 하는 메모리 내 데이터베이스를 사용합니다. PATCH를 호출하기 전에 데이터베이스에 항목이 포함되어야 합니다. POST를 호출하여 PATCH를 호출하기 전에 데이터베이스에 항목이 있는지 확인합니다.

PATCH 엔드포인트는 nullable 속성이 있는 TodoPatchDto 클래스를 사용하여 부분 업데이트를 제대로 처리합니다. nullable 속성을 사용하면 엔드포인트가 제공되지 않은 필드(null)와 명시적으로 값으로 설정된 필드(부울 필드의 경우 false 포함)를 구분할 수 있습니다. nullable 속성이 없으면 nullable이 아닌 bool은 기본적으로 false로 설정되며, 해당 필드가 요청에 포함되지 않은 경우 기존 true 값을 덮어쓸 수 있습니다.

• 다음 코드를 사용하여 TodoPatchDto.cs라는 파일을 만듭니다.

public class TodoPatchDto
{
    public string? Name { get; set; }
    public bool? IsComplete { get; set; }
}

클래스는 TodoPatchDto nullable 속성(string? 및)을 사용하여 요청에 제공되지 않은 필드와 bool?명시적으로 값으로 설정된 필드를 구분합니다.

• Program.cs에서 MapPut 엔드포인트 바로 다음에 다음 PATCH 엔드포인트를 추가합니다.

Visual Studio

app.MapPatch("/todoitems/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

Visual Studio Code

app.MapPatch("/todoitems/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

이 메서드는 메서드와 비슷하 MapPut 지만 HTTP PATCH를 사용하고 요청에 제공된 필드만 업데이트합니다. 성공적인 응답은 204(콘텐츠 없음)를 반환합니다.

Note

PATCH 작업을 통해 리소스를 부분적으로 업데이트할 수 있습니다. JSON 패치 문서를 사용하는 고급 부분 업데이트는 ASP.NET Core 웹 API의 JsonPatch를 참조하세요.

PATCH 엔드포인트를 테스트하십시오

Visual Studio

• Ctrl+F5 키를 눌러 새 PATCH 엔드포인트를 사용하여 앱을 다시 빌드하고 실행합니다.

Visual Studio Code

• 새 PATCH 엔드포인트를 사용하여 다시 빌드되도록 앱을 다시 실행합니다. Visual Studio Code에서 Ctrl+(Windows) 또는 컨트롤+(macOS)를 눌러 디버깅 없이 앱을 실행합니다.

이 샘플에서는 앱이 시작될 때마다 초기화해야 하는 메모리 내 데이터베이스를 사용합니다. PATCH를 호출하기 전에 데이터베이스에 항목이 포함되어야 합니다. POST를 호출하여 PATCH를 호출하기 전에 데이터베이스에 항목이 있는지 확인합니다.

Todo 항목 name 의 Id = 1 속성만 업데이트하고 이름을 "run errands".로 설정합니다.

Visual Studio

• 엔드포인트 탐색기에서 새로 고침 단추를 선택합니다. 그런 다음 PATCH 엔드포인트를 마우스 오른쪽 단추로 클릭하고 요청 생성을 선택합니다.

  다음 콘텐츠가 TodoApi.http 파일에 추가됩니다.

  PATCH {{TodoApi_HostAddress}}/todoitems/{id}

  ###

• PATCH 요청 줄에서 `{id}`를 `1`로 교체합니다.

• PATCH 요청 줄 바로 다음에 다음 줄을 추가합니다.

  Content-Type: application/json

  {
    "name": "run errands"
  }

앞의 코드는 업데이트할 필드만 있는 Content-Type 헤더 및 JSON 요청 본문을 추가합니다.

• 새 PATCH 요청 줄 위에 있는 요청 보내기 링크를 선택합니다.

Visual Studio Code

Scalar UI를 사용하여 PATCH 요청을 보냅니다.

• 새 PATCH 엔드포인트가 표시되도록 브라우저에서 스칼라 페이지를 새로 고칩니다.

• PATCH /todoitems/{id}를 선택한 다음, 테스트 요청을 선택합니다.

• ID 필드를 1로 설정합니다.

• 요청 본문을 다음 JSON으로 설정합니다.

  {
    "name": "run errands"
  }

• 보내기를 선택합니다.

PATCH 요청이 앱으로 전송되고 응답 창에 응답 이 표시됩니다. 응답 본문이 비어 있고 상태 코드는 204입니다.

DELETE 엔드포인트 살펴보기

Program.cs 파일에는 MapDelete로 정의된 단일 DELETE 엔드포인트가 포함되어 있습니다:

Visual Studio

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

Visual Studio Code

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

DELETE 엔드포인트를 테스트하세요

Visual Studio

• 엔드포인트 탐색기에서 DELETE 엔드포인트를 마우스 오른쪽 단추로 클릭하고 요청 생성을 선택합니다.

  DELETE 요청이 TodoApi.http에 추가됩니다.

• DELETE 요청 줄에서 {id}을 1으로 바꾸세요. DELETE 요청은 다음 예제와 같습니다.

  DELETE {{TodoApi_HostAddress}}/todoitems/1

  ###

• DELETE 요청에 대한 요청 보내기 링크를 선택합니다.

Visual Studio Code

스칼라 UI를 사용하여 DELETE 요청을 보냅니다.

• DELETE /todoitems/{id}를 선택한 다음, 요청을 테스트합니다.
• ID 필드를 설정하고 1를 선택합니다.

DELETE 요청이 앱으로 전송되고 응답 창에 응답이 표시됩니다. 응답 본문이 비어 있고 상태 코드는 204입니다.

MapGroup API 사용

• 다음 단계에서는 Program.cs 파일을 수정하므로 이러한 변경을 수행하기 전에 앱을 중지하세요. 브라우저에서 스칼라 페이지를 실행 상태로 둡니다.

Visual Studio

• 앱을 중지하려면 Visual Studio 도구 모음에서 중지 단추(빨간색 사각형)를 선택합니다.

Visual Studio Code

• 앱을 중지하려면 ShiftF5+ 누릅니다.

작성한 Program.cs 파일은 엔드포인트를 설정할 때마다 todoitems URL 접두사를 반복해서 사용합니다. API에는 공통 URL 접두사를 사용하는 엔드포인트 그룹이 있는 경우가 많으며, 이 메서드는 MapGroup 이러한 그룹을 구성하는 데 도움이 됩니다. 반복 코드를 줄이고, 메서드와 같은 RequireAuthorizationWithMetadata메서드를 한 번의 호출로 전체 엔드포인트 그룹을 사용자 지정할 수 있습니다.

• Program.cs의 내용을 다음 코드로 바꿉니다.

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", async (TodoDb db) =>
    await db.Todos.ToListAsync());

todoItems.MapGet("/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

todoItems.MapGet("/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

todoItems.MapPost("/", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

todoItems.MapPut("/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapPatch("/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapDelete("/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", async (TodoDb db) =>
    await db.Todos.ToListAsync());

todoItems.MapGet("/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

todoItems.MapGet("/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

todoItems.MapPost("/", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

todoItems.MapPut("/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapPatch("/{id}", async (int id, TodoPatchDto inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

todoItems.MapDelete("/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.NoContent();
    }

    return Results.NotFound();
});

app.Run();

위의 코드에는 다음과 같은 변경 내용이 있습니다.

• URL 접두사 var todoItems = app.MapGroup("/todoitems");을 사용하여 그룹을 설정하도록 /todoitems을 추가합니다.

• 모든 app.Map<HttpVerb> 메서드를 todoItems.Map<HttpVerb>로 변경합니다.

• /todoitems 메서드 호출에서 URL 접두사 Map<HttpVerb>를 제거합니다.

• 앱을 실행하고 엔드포인트를 테스트하여 동일하게 작동하는지 확인합니다.

TypedResults API 사용

다음 단계에서는 Program.cs 파일을 수정하므로 이러한 변경을 수행하기 전에 앱을 중지하세요. 브라우저에서 스칼라 페이지를 실행 상태로 둡니다.

TypedResults을 반환하는 것은 Results을 반환하는 것보다 테스트 용이성, 그리고 OpenAPI가 엔드포인트를 설명하기 위한 응답 형식 메타데이터를 자동으로 반환하는 등 여러 가지 이점이 있습니다. 자세한 내용은 TypedResults vs Results를 참조하세요.

• Map<HttpVerb> 메서드는 람다를 사용하는 대신 경로 처리기 메서드를 호출할 수 있습니다. 예제를 보려면 다음 코드로 Program.cs를 업데이트합니다.

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

이제 Map<HttpVerb> 코드는 람다 대신 메서드를 호출합니다.

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

다음 메서드는 IResult를 구현하고 TypedResults에 의해 정의된 개체를 반환합니다.

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(Todo todo, TodoDb db)
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return TypedResults.Created($"/todoitems/{todo.Id}", todo);
}

static async Task<IResult> UpdateTodo(int id, Todo inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

단위 테스트는 이러한 메서드를 호출하고 올바른 형식을 반환하는지 테스트할 수 있습니다. 예를 들어 메서드가 GetAllTodos인 경우:

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.ToArrayAsync());
}

단위 테스트 코드는 Ok<Todo[]> 형식의 개체가 처리기 메서드에서 반환되는지 확인할 수 있습니다. 다음은 그 예입니다.

public async Task GetAllTodos_ReturnsOkOfTodosResult()
{
    // Arrange
    var db = CreateDbContext();

    // Act
    var result = await TodosApi.GetAllTodos(db);

    // Assert: Check for the correct returned type
    Assert.IsType<Ok<Todo[]>>(result);
}

초과 게시 방지

현재 API는 Todo에 추가한 Secret 속성을 포함하여 전체 개체를 노출합니다. 프로덕션 애플리케이션에서 모델의 하위 집합을 사용하여 클라이언트가 입력하고 받을 수 있는 데이터를 제한합니다. 보안이 이러한 제한의 주요 원인입니다. 모델의 이 하위 집합을 일반적으로 DTO(데이터 전송 개체), 입력 모델 또는 뷰 모델이라고 합니다. 이 문서에서는 DTO를 사용합니다.

DTO를 사용하여 다음을 수행합니다.

• 초과 게시를 방지합니다.
• 클라이언트에서 볼 수 없는 속성을 숨깁니다.
• 페이로드 크기를 줄이기 위해 일부 속성을 생략합니다.
• 중첩된 개체를 포함하는 개체 그래프를 평면화합니다. 클라이언트에는 평면화된 개체 그래프가 더 편리할 수 있습니다.

이 앱은 Secret 필드를 숨겨야 하지만 관리 앱이 필드를 노출하도록 선택할 수 있습니다.

• 다음 단계에서는 파일을 추가하므로 변경하기 전에 앱을 중지합니다. 브라우저에서 스칼라 페이지를 실행 상태로 둡니다.

• 다음 코드를 사용하여 TodoItemDTO.cs라는 파일을 만듭니다.

public class TodoItemDTO
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }

    public TodoItemDTO() { }
    public TodoItemDTO(Todo todoItem) =>
    (Id, Name, IsComplete) = (todoItem.Id, todoItem.Name, todoItem.IsComplete);
}

• 이 DTO 모델을 사용하려면 파일의 Program.cs 내용을 다음 코드로 바꿉니다.

Visual Studio

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Select(x => new TodoItemDTO(x)).ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).Select(x => new TodoItemDTO(x)).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(new TodoItemDTO(todo))
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(TodoItemDTO todoItemDTO, TodoDb db)
{
    var todoItem = new Todo
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    db.Todos.Add(todoItem);
    await db.SaveChangesAsync();

    todoItemDTO = new TodoItemDTO(todoItem);

    return TypedResults.Created($"/todoitems/{todoItem.Id}", todoItemDTO);
}

static async Task<IResult> UpdateTodo(int id, TodoItemDTO todoItemDTO, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = todoItemDTO.Name;
    todo.IsComplete = todoItemDTO.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddOpenApi();
var app = builder.Build();

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

var todoItems = app.MapGroup("/todoitems");

todoItems.MapGet("/", GetAllTodos);
todoItems.MapGet("/complete", GetCompleteTodos);
todoItems.MapGet("/{id}", GetTodo);
todoItems.MapPost("/", CreateTodo);
todoItems.MapPut("/{id}", UpdateTodo);
todoItems.MapPatch("/{id}", PatchTodo);
todoItems.MapDelete("/{id}", DeleteTodo);

app.Run();

static async Task<IResult> GetAllTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Select(x => new TodoItemDTO(x)).ToArrayAsync());
}

static async Task<IResult> GetCompleteTodos(TodoDb db)
{
    return TypedResults.Ok(await db.Todos.Where(t => t.IsComplete).Select(x => new TodoItemDTO(x)).ToListAsync());
}

static async Task<IResult> GetTodo(int id, TodoDb db)
{
    return await db.Todos.FindAsync(id)
        is Todo todo
            ? TypedResults.Ok(new TodoItemDTO(todo))
            : TypedResults.NotFound();
}

static async Task<IResult> CreateTodo(TodoItemDTO todoItemDTO, TodoDb db)
{
    var todoItem = new Todo
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    db.Todos.Add(todoItem);
    await db.SaveChangesAsync();

    todoItemDTO = new TodoItemDTO(todoItem);

    return TypedResults.Created($"/todoitems/{todoItem.Id}", todoItemDTO);
}

static async Task<IResult> UpdateTodo(int id, TodoItemDTO todoItemDTO, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    todo.Name = todoItemDTO.Name;
    todo.IsComplete = todoItemDTO.IsComplete;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> PatchTodo(int id, TodoPatchDto inputTodo, TodoDb db)
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return TypedResults.NotFound();

    if (inputTodo.Name is not null) todo.Name = inputTodo.Name;
    if (inputTodo.IsComplete is not null) todo.IsComplete = inputTodo.IsComplete.Value;

    await db.SaveChangesAsync();

    return TypedResults.NoContent();
}

static async Task<IResult> DeleteTodo(int id, TodoDb db)
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return TypedResults.NoContent();
    }

    return TypedResults.NotFound();
}

• 앱을 실행하고 필드를 제외한 Secret 모든 필드를 게시하고 가져올 수 있는지 확인합니다.

완료된 샘플을 사용한 문제 해결

해결할 수 없는 문제가 발생한 경우 완료된 프로젝트와 코드를 비교합니다. 완료된 프로젝트를 보거나 다운로드합니다(다운로드 방법).

다음 단계

• JSON serialization 옵션을 구성합니다.
• 오류 및 예외 처리: 최소 API 앱에 대한 환경에서는 개발자 예외 페이지 가 Development 기본적으로 사용하도록 설정됩니다. 오류 및 예외를 처리하는 방법에 대한 자세한 내용은 ASP.NET Core API에서 오류 처리를 참조하세요.
• 최소 API 앱을 테스트하는 예제는 이 GitHub 샘플을 참조하세요.
• 최소 API에서 OpenAPI를 지원합니다.
• 빠른 시작: Azure에 게시합니다.
• ASP.NET Core 최소 API 구성

Learn more

최소 API 빠른 참조 참조하세요.