Linux에서 .NET Aspire에 Swagger UI 추가하기

Tim Corey

7m 24s

브라우저에 URL을 수동으로 입력하여 API 엔드포인트를 테스트하는 것은 빠른 확인에 적합하지만, 다른 HTTP 동사와 요청 본문이 있는 두 개 이상의 라우트가 있는 경우에는 실패합니다. Swagger UI는 모든 엔드포인트를 호출하고, 응답을 확인하며, 별도의 클라이언트를 작성하거나 curl 플래그를 기억하지 않고 매개변수를 실험할 수 있는 인터랙티브한 브라우저 기반 패널을 제공합니다.

그의 비디오 "Adding Swagger UI to .NET Aspire on Linux"에서 Tim Corey는 이전 에피소드에서 Tiny Ticket 프로젝트를 이어받아 기존 OpenAPI 구성 위에 Swagger UI를 추가합니다. 이 과정은 세 줄의 코드와 하나의 NuGet 패키지를 필요로 합니다. 그 다음 그는 데이터베이스 연결 문제 해결을 포함하여 Swagger 인터페이스를 통해 티켓 엔드포인트를 호출하는 것을 시연합니다. C# on Linux 시리즈에서 API를 구축 중이거나 .NET 프로젝트에서 Swagger를 연결하는 간단한 참조를 원한다면 이 기사에서는 모든 단계를 다룹니다.

Swashbuckle NuGet Install-Package

[0:38 - 1:35] Tim이 VS Code에서 Tiny Ticket 프로젝트를 열고 API 서비스의 Program.cs로 이동합니다. API에는 이미 이전 에피소드의 GET /api/tickets 엔드포인트가 있지만 이를 호출하려면 URL을 수동으로 구성해야 했습니다. 적절한 테스트 인터페이스를 추가하려면 첫 번째 단계로 Swagger UI 패키지를 설치해야 합니다.

API 프로젝트를 오른쪽 클릭하고 "NuGet 패키지 추가"를 선택한 다음 Swashbuckle.AspNetCore.SwaggerUI을 검색합니다. Tim은 가장 최신 버전(녹화 당시 10.1.7)을 설치합니다. 설치 후 패키지 참조는 프로젝트 파일에 나타납니다. 프로젝트가 기본 Aspire 서비스 구성을 통해 OpenAPI 지원을 이미 포함하고 있기 때문에 다른 종속성은 필요하지 않습니다.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Program.cs에서 Swagger UI 구성

[1:35 - 3:12] 패키지가 설치된 후 구성은 Program.cs의 개발 전용 블록에 들어갑니다. 프로젝트에는 이미 app.MapOpenApi()이 등록되어 있으며, 이는 실행 시 OpenAPI 명세 파일을 생성합니다. Swagger UI는 그 파일이 어디에 있는지와 엔드포인트 그룹에 무엇을 표시할지 알면 됩니다.

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

SwaggerEndpoint 호출은 .NET이 자동으로 생성하는 OpenAPI 명세를 가리킵니다. 두 번째 매개변수는 Swagger UI 드롭다운에 표시될 이름입니다. Tim은 이 세 줄이 전체 Swagger 설정이라고 강조합니다. UI를 사용자 정의하거나 엔드포인트 그룹핑, 인증 헤더 추가 등을 위한 더 많은 구성을 추가할 수 있지만 개발 테스트 도구로는 기본값이 충분합니다.

알아둘 만한 세부사항: .NET 9 이후 새로운 API 프로젝트에는 기본적으로 Swagger가 포함되지 않습니다. Microsoft는 OpenAPI를 표준으로 제공하고 개발자가 선호하는 UI 레이어를 선택할 수 있도록 관계를 나누었습니다. Swagger, Scalar 및 다른 도구들은 모두 같은 OpenAPI 사양 파일을 사용하므로 특정 뷰어에 고정되지 않습니다.

Swagger 인터페이스 실행 및 검증

[3:12 - 6:07] 저장 후 Tim은 프로젝트를 실행 및 디버그 패널을 통해 실행합니다. Aspire 대시보드가 로드되고 API 서비스가 실행 중으로 표시되면, 그는 API의 URL로 이동하여 경로에 /swagger을 추가합니다.

Swagger UI는 "Ticket App API v1" 라벨로 로드되며 사용 가능한 엔드포인트를 나열합니다. 루트 엔드포인트(/)는 간단한 상태 메시지를 반환하고, /api/tickets는 데이터베이스에서 티켓 데이터를 반환합니다.

Tim은 루트 엔드포인트에서 "Try it out"을 클릭하고 실행합니다. 응답은 200 상태와 확인 메시지를 담고 돌아옵니다. 그런 다음 그는 /api/tickets 엔드포인트로 이동하여 실행을 클릭합니다. 여기서 문제 해결이 시작됩니다.

첫 번째 시도는 연결 오류로 실패합니다: "SQL 서버에 연결을 설정할 때 네트워크 관련 또는 인스턴스 관련 오류가 발생했습니다." 데이터베이스 컨테이너가 컴퓨터 재부팅 후 시작되지 않았습니다. Tim은 Portainer를 열고 SQL 서버 Docker 컨테이너를 찾아 시작합니다. 컨테이너 초기화가 완료되면 Swagger로 돌아가 요청을 다시 실행합니다. 이번에는 응답이 데이터베이스에 저장된 세 개의 테스트 티켓과 함께 200으로 돌아옵니다.

이 순서는 통합 테스트가 실제 인프라와의 문제를 드러낼 수 있으며, 단위 테스트 및 모의 데이터로는 불가능하다는 실용적인 상기시킴입니다. 데이터베이스 컨테이너는 부팅 시 자동 시작으로 설정되어 있지 않아, 재부팅 후 첫 번째 API 호출은 컨테이너 상태를 먼저 확인하지 않으면 실패할 것입니다.

앞으로 나올 내용: CRUD 엔드포인트

[6:07 - 7:20] Tim은 시리즈의 다가오는 에피소드를 미리 보여줍니다. Tiny Ticket API에는 현재 GET /api/tickets 엔드포인트만 있으며, 이는 spTickets_GetAll 저장 프로시저에 매핑됩니다. 데이터베이스의 남은 저장 프로시저들(ID로 검색, 삽입, 업데이트, 삭제) 각각이 올바른 HTTP 동사를 가진 API 엔드포인트를 필요로 합니다: 검색을 위한 GET, 생성을 위한 POST, 업데이트를 위한 PUT, 제거를 위한 DELETE.

그는 각 엔드포인트가 같은 패턴을 따르며 구현이 간단하다는 것을 언급하지만, 각 파트를 독립적으로 참조할 수 있도록 다가오는 비디오들은 각각 개별적으로 다룰 것입니다. 시리즈를 작은 집중된 에피소드로 나누기로 한 선택은 더 긴 비디오를 탐색하지 않고 필요한 엔드포인트 유형으로 직접 이동할 수 있다는 것을 의미합니다.

결론

[7:20 - 7:24] Linux에서 .NET Aspire 프로젝트에 Swagger UI를 추가하려면 하나의 NuGet 패키지와 Program.cs의 세 줄 구성이 필요합니다. OpenAPI 사양 파일은 기본 Aspire 서비스 설정에 의해 이미 생성되므로 Swagger는 그 파일과 표시 이름만 필요합니다. 여기에서 API의 모든 엔드포인트는 별도의 클라이언트를 빌드하지 않고 브라우저를 통해 테스트할 수 있습니다.

Tim이 재부팅 후에 마주했던 데이터베이스 연결 문제는 실용적인 점을 다시 한 번 강조합니다: 개발 스택에 컨테이너가 포함되어 있다면 API 엔드포인트를 테스트하기 전에 그들이 실행 중인지 확인하세요. Swagger는 해당 확인에 대한 빠른 피드백 루프를 제공합니다.

시리즈 내비게이션: 이 기사는 Linux에서 Tiny Ticket 앱을 구축하는 C# 시리즈의 일부입니다. 이전: Setting Up .NET Aspire on Linux. 다음: ID로 검색 엔드포인트 추가하기.

팁 예시: Swagger 외에 다른 OpenAPI 뷰어를 선호한다면 Scalar나 RapiDoc 같은 패키지를 설치하고 동일한 /openapi/v1.json 엔드포인트를 가리키세요. 사양 파일은 UI에 구애받지 않으므로 API 구성을 변경하지 않고 뷰어를 교체할 수 있습니다.

YouTube 채널에서 전체 비디오를 보고 Linux 시리즈의 C#에서 API 구축에 대한 더 많은 통찰력을 얻으세요.