ProgrammingLanguageC#

.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 이상

시작하기 🚀

1단계: .NET Core 웹 API 프로젝트 만들기

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

2단계: Swashbuckle.AspNetCore NuGet 패키지 설치

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

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

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

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

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

4단계: Swagger 구성

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

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

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

5단계: API Endpoint 문서 생성

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

1
2
3
4
5
6
7
8
9
/// <summary>
/// Gets all items.
/// </summary>
/// <returns>All items.</returns>
[HttpGet]
public IEnumerable<Item> GetAll ()
{
    return repository.GetAll();
}

6단계: Swagger UI를 사용하여 API Endpoint 테스트

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

결론

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

Share