.NET Core에서 Swagger를 사용하는 방법

Swagger는 RESTful API를 문서화하고 테스트하는 데 널리 사용되는 오픈 소스 도구입니다. 개발자가 API를 테스트하고 실시간으로 문서를 생성할 수 있는 사용자 친화적인 인터페이스를 제공합니다.

이 글에서는 .NET Core와 함께 Swagger를 사용하여 API Endpoint를 문서화하고 테스트하는 방법을 살펴보겠습니다.

Endpoint는 API가 RESTful API를 인터페이스를 통해 서버의 리소스에 액세스 할 수 있도록 해주는 URL입니다.

전제 조건 🛠️

• 컴퓨터에 .NET Core 3.1 이상이 설치되어 있어야 함
• RESTful API 아키텍처에 대한 기본 이해
• Visual Studio Code 또는 Visual Studio 2019 이상

시작하기 🚀

.NET Core 웹 API 프로젝트 만들기

첫 번째 단계는 새 .NET Core Web API 프로젝트를 만드는 것입니다. Visual Studio 또는 Visual Studio Code를 열고 새 .NET Core Web API 프로젝트를 만듭니다.

Swashbuckle.AspNetCore NuGet 패키지 설치

Swagger는 .NET Core용 NuGet 패키지로 제공됩니다. 설치하려면 IDE에서 NuGet 패키지 관리자를 열고 Swashbuckle.AspNetCore를 검색하세요. 최신 버전의 패키지를 설치하십시오.

애플리케이션 파이프라인에 Swagger 미들웨어 추가

Startup.cs 파일의 구성 메서드에 다음 코드를 추가하여 Swagger 미들웨어를 애플리케이션 파이프라인에 추가합니다.

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint( "/swagger/v1/swagger.json" , "My API V1" );
});

그러면 미들웨어 파이프라인에 Swagger가 추가되고 개발자가 API를 테스트할 수 있는 UI가 생성됩니다.

Swagger 구성

SwaggerGenOptions 클래스를 사용하여 Swagger를 구성할 수 있습니다. 이 클래스는 Swagger에서 생성된 문서를 사용자 정의하는 메서드를 제공합니다. Swagger를 구성하려면 Startup.cs 파일의 ConfigureServices 메서드에 다음 코드를 추가하세요.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc( "v1" , new OpenApiInfo { Title = "My API" , Version = "v1" });
});

그러면 SwaggerGen 미들웨어가 애플리케이션 파이프라인에 추가되고 Swagger UI가 구성됩니다.

API Endpoint 문서 생성

Swagger는 XML 문서 주석을 사용하여 API Endpoint에 대한 문서를 생성합니다. API Endpoint에 XML 주석을 추가하여 문서화하세요. 다음은 GET 엔드포인트에 XML 문서 주석을 추가하는 방법의 예입니다.

/// <summary>
/// Gets all items.
/// </summary>
/// <returns>All items.</returns>
[HttpGet]
public IEnumerable<Item> GetAll ()
{
    return repository.GetAll();
}

Swagger UI를 사용하여 API Endpoint 테스트

애플리케이션을 실행하고 Swagger UI Endpoint로 이동합니다. 그러면 개발자가 API Endpoint를 테스트할 수 있는 사용자 친화적인 인터페이스를 제공하는 Swagger UI가 열립니다.

결론

Swagger는 RESTful API를 문서화하고 테스트하기 위한 강력한 도구입니다. 개발자가 API를 테스트하고 실시간으로 문서를 생성할 수 있는 사용자 친화적인 인터페이스를 제공합니다. 이 글에서는 .NET Core와 함께 Swagger를 사용하여 API Endpoint를 문서화하고 테스트하는 방법을 살펴보았습니다. Swagger를 사용하면 API가 잘 문서화되고 테스트되어 개발자가 더 쉽게 API를 사용할 수 있도록 보장할 수 있습니다.