ASP.NET Core Web API 개발: Swagger와 Entity Framework Core Code-First 적용

RESTful API를 개발할 때 API 문서화는 필수적인 요소입니다. Swagger(현 OpenAPI Specification)는 REST API를 위한 표준화되고 언어 독립적인 인터페이스를 정의하는 것을 목표로 합니다. 이를 통해 개발자와 시스템 모두 소스 코드나 별도의 문서 없이도 다양한 서비스의 기능을 쉽게 파악하고 이해할 수 있습니다. Swagger로 API가 정의되면, 클라이언트는 최소한의 구현 로직만으로도 원격 서비스와 상호작용할 수 있게 되어, API 호출 시 발생하는 불확실성을 크게 줄여줍니다.

이 문서는 ASP.NET Core Web API 프로젝트에 Swagger를 통합하고, Entity Framework Core(EF Core)의 Code-First 접근 방식을 사용하여 데이터베이스를 설정하는 과정을 안내합니다.

ASP.NET Core Web API 프로젝트 생성

먼저, 새로운 ASP.NET Core Web API 프로젝트를 생성하는 것으로 시작합니다. Visual Studio 또는 .NET CLI를 사용하여 프로젝트를 만들 수 있습니다.

dotnet new webapi -n MyApiProject
cd MyApiProject

Entity Framework Core (Code-First) 설정

Web API 프로젝트에 데이터베이스 기능을 통합하기 위해 Entity Framework Core(EF Core)의 Code-First 접근 방식을 사용해 보겠습니다. Code-First는 코드에서 데이터 모델을 정의하고, 이를 기반으로 데이터베이스 스키마를 생성하거나 업데이트하는 방식입니다. 이를 위해 다음 NuGet 패키지들을 설치해야 합니다.

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

엔티티(Entity) 정의

다음으로, 데이터베이스에 저장될 엔티티(Entity)를 정의합니다. 프로젝트 내에 Models 폴더를 생성하고, 간단한 Item 엔티티 클래스를 추가합니다.

using System.ComponentModel.DataAnnotations;

namespace MyApiProject.Models
{
    public class Item
    {
        [Key] // 기본 키로 설정
        public int ItemId { get; set; }

        [Required] // 필수 필드로 설정
        [StringLength(50)] // 최대 길이 50으로 설정
        public string ItemName { get; set; }

        // 추가 속성을 원한다면 여기에 정의합니다.
        // public decimal Price { get; set; }
    }
}

DbContext 클래스 생성

엔티티 정의 후에는 데이터베이스와의 상호작용을 담당하는 DbContext 클래스를 생성해야 합니다. Models 폴더 내에 ApplicationDbContext.cs 파일을 만들고, DbContext를 상속받아 구현합니다.

using Microsoft.EntityFrameworkCore;

namespace MyApiProject.Models
{
    public class ApplicationDbContext : DbContext
    {
        public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
            : base(options)
        {
        }

        // Item 엔티티를 위한 DbSet 추가
        public DbSet<Item> Items { get; set; }
    }
}

DbContext 구성

ApplicationDbContext가 데이터베이스에 연결될 수 있도록 설정해야 합니다. 이는 주로 Program.cs의 AddDbContext를 통해 의존성 주입(Dependency Injection) 컨테이너에 등록하는 방식으로 이루어집니다. appsettings.json 파일에 연결 문자열을 정의하고, Program.cs에서 이를 사용합니다.

먼저, appsettings.json 파일에 데이터베이스 연결 문자열을 추가합니다.

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=MyApiDb;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

다음으로, Program.cs 파일을 수정하여 DbContext를 서비스 컨테이너에 등록합니다.

using Microsoft.EntityFrameworkCore;
using MyApiProject.Models; // ApplicationDbContext의 네임스페이스

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();

// DbContext를 서비스에 추가
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

// ... 다른 서비스 등록 ...

var app = builder.Build();

// Configure the HTTP request pipeline.
// ...

데이터베이스 마이그레이션

DbContext 및 엔티티 설정이 완료되면, Code-First 마이그레이션을 통해 데이터베이스 스키마를 생성하거나 업데이트할 수 있습니다. 다음 명령어를 패키지 관리자 콘솔 또는 .NET CLI에서 실행합니다.

초기 마이그레이션 추가: 데이터베이스 스키마의 초기 버전을 생성합니다.
```
dotnet ef migrations add InitialCreate
    
```
이 명령은 Migrations 폴더에 마이그레이션 파일을 생성합니다.
데이터베이스 업데이트: 생성된 마이그레이션을 기반으로 실제 데이터베이스를 생성하거나 업데이트합니다.
```
dotnet ef database update
    
```
이 명령을 실행하면 MyApiDb (또는 appsettings.json에 정의된 데이터베이스 이름) 데이터베이스와 Items 테이블이 생성됩니다.

Swagger (Swashbuckle) 통합

이제 API 문서화를 위한 Swagger(Swashbuckle.AspNetCore)를 통합합니다. Swashbuckle은 ASP.NET Core 애플리케이션에 Swagger/OpenAPI 기능을 쉽게 추가할 수 있도록 해주는 라이브러리입니다. 다음 NuGet 패키지를 설치합니다.

dotnet add package Swashbuckle.AspNetCore

Swagger 서비스 등록

Program.cs 파일에 Swagger 서비스를 등록합니다. builder.Services.AddSwaggerGen 메서드를 사용하여 Swagger 문서의 기본 정보를 설정할 수 있습니다.

// Program.cs
using Microsoft.OpenApi.Models; // OpenApiInfo를 사용하기 위한 네임스페이스

// ... (existing code for builder and AddControllers) ...

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Item Management API",
        Version = "v1",
        Description = "ASP.NET Core Web API 예제",
        Contact = new OpenApiContact
        {
            Name = "개발자 이름",
            Email = "developer@example.com",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "라이선스 정보",
            Url = new Uri("https://example.com/license")
        }
    });
});

var app = builder.Build(); // 이전에 작성된 빌드 코드와 통합

Swagger 미들웨어 설정

다음으로, Program.cs의 애플리케이션 파이프라인 구성 부분에서 Swagger 및 Swagger UI 미들웨어를 활성화합니다. 개발 환경에서만 Swagger UI를 사용하도록 구성하는 것이 일반적입니다.

// Program.cs
// ... (existing code for app.Build()) ...

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Item Management API V1");
        options.RoutePrefix = "api-docs"; // 기본 경로 'swagger' 대신 'api-docs'로 변경 가능
    });
}

app.UseAuthorization();
app.MapControllers();
app.Run();

이제 애플리케이션을 실행하고 웹 브라우저에서 http://localhost:포트번호/api-docs (혹은 설정한 RoutePrefix)로 접속하면, Swagger UI를 통해 API 문서를 확인할 수 있습니다.

XML 주석(Documentation Comments) 활성화

API에 대한 주석(XML Documentation Comments)을 Swagger UI에 표시하려면 몇 가지 추가 설정이 필요합니다.

프로젝트 설정: 프로젝트 파일(.csproj)을 열고 <PropertyGroup> 내에 다음 설정을 추가하여 XML 문서 파일 생성을 활성화합니다.
```
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
```

컨트롤러에 주석 추가: API 컨트롤러 액션 및 모델에 /// 주석을 추가합니다. 다음은 예시 컨트롤러입니다.

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using MyApiProject.Models;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace MyApiProject.Controllers
{
    /// <summary>
    /// 아이템 관련 API를 제공합니다.
    /// </summary>
    [ApiController]
    [Route("[controller]")]
    public class ItemsController : ControllerBase
    {
        private readonly ApplicationDbContext _dbContext;

        public ItemsController(ApplicationDbContext dbContext)
        {
            _dbContext = dbContext;
        }

        /// <summary>
        /// 모든 아이템 목록을 가져옵니다.
        /// </summary>
        /// <returns>아이템 목록</returns>
        [HttpGet]
        public async Task<ActionResult<IEnumerable<Item>>> GetItems()
        {
            return await _dbContext.Items.ToListAsync();
        }

        /// <summary>
        /// 특정 ID의 아이템을 가져옵니다.
        /// </summary>
        /// <param name="id">아이템 ID</param>
        /// <returns>해당 ID의 아이템</returns>
        [HttpGet("{id}")]
        [ProducesResponseType(StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<ActionResult<Item>> GetItem(int id)
        {
            var item = await _dbContext.Items.FindAsync(id);

            if (item == null)
            {
                return NotFound();
            }

            return item;
        }

        // 추가 CRUD 작업 (POST, PUT, DELETE)을 여기에 정의할 수 있습니다.
    }
}

Swagger 설정 업데이트: Program.cs의 AddSwaggerGen 부분에 XML 문서 파일을 포함하도록 설정합니다.

using System.Reflection; // Assembly를 사용하기 위한 네임스페이스
using System.IO; // Path를 사용하기 위한 네임스페이스

// ... (AddSwaggerGen options) ...
options.SwaggerDoc("v1", new OpenApiInfo
{
    // ...
});

// XML 주석 파일 경로 설정 및 포함
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));

이제 애플리케이션을 다시 실행하고 http://localhost:포트번호/api-docs (혹은 설정한 RoutePrefix)로 접속하면, API 설명과 각 엔드포인트에 대한 주석이 Swagger UI에 표시되는 것을 확인할 수 있습니다.

태그: ASP.NET Core Web API swagger Entity Framework Core code-first

7월 21일 03:21에 게시됨

괴물 클럽