.NET 9 API에서 Swagger를 대체할 4가지 옵션

표준 API 프로젝트 설정하기

Tim은 먼저 Visual Studio에서 표준 ASP.NET Core Web API 템플릿을 선택하여 최소한의 API 프로젝트를 생성합니다.

그는 OpenAPI 지원을 추가하는 옵션을 선택하는 것을 강조하는데, 이렇게 하면 프로젝트에 JSON 파일 엔드포인트를 통해 필요한 OpenAPI 문서 생성 기능이 포함되기 때문입니다.

프로젝트가 실행되면 Tim은 기본 OpenAPI 문서 URL(예: /swagger/v1/swagger.json)로 이동하여 원시 OpenAPI 사양을 확인합니다. 이 파일에는 GET, POST, DELETE와 같은 지원되는 동사를 포함하여 API 엔드포인트에 대한 구조화된 메타데이터가 포함되어 있습니다.

기능은 정상적으로 작동하지만, 팀은 원본 OpenAPI 문서를 보는 방식이 사용자 친화적이지 않다고 지적합니다. 더 나은 웹 기반 문서 인터페이스를 제공하기 위해 그는 개발자와 사용자 경험을 향상시키는 네 가지 외부 도구를 소개합니다.

옵션 1: Swagger UI – 익숙한 경험

Swagger UI는 더 이상 기본적으로 포함되지는 않지만 여전히 매우 인기 있는 도구입니다. Tim은 필요한 NuGet 패키지인 dotnet: Swashbuckle.AspNetCore.SwaggerUI를 사용하여 이를 복원하는 방법을 보여줍니다.

새 프로젝트에 Swagger UI를 설정한 후, 9시 43분에 간소화된 구문을 사용하여 미들웨어를 구성하고 실행 URL을 /swagger로 설정합니다. 이 UI는 개발자가 엔드포인트를 확인하고, 요청 매개변수를 이해하고, 브라우저에서 테스트할 수 있는 사용자 친화적인 API 문서화 인터페이스를 제공합니다.

Swagger UI는 이제 외부 도구이지만 여전히 OpenAPI 사양을 지원하며 개발 중 기본적인 문서화 요구 사항을 충족하는 데 가장 적합한 선택지 중 하나입니다.

옵션 2: ReDoc – 깔끔하고 읽기 전용 API 문서

Tim이 사용하는 두 번째 도구는 ReDoc입니다. ReDoc은 OpenAPI 문서를 세련된 읽기 전용 HTML 사이트로 변환해 줍니다. Swashbuckle.AspNetCore.ReDoc OpenAPI 패키지를 추가한 후, 그는 문서를 /api/docs에 매핑합니다.

Swagger UI와 달리 ReDoc은 엔드포인트 테스트를 허용하지 않습니다. 하지만 외부 사용자 및 고객에게 적합한 웹 기반 문서 인터페이스라는 점에서 뛰어난 성능을 발휘합니다. REST API를 정의하고 구조화된 문서를 표시하는 데만 집중한다면 ReDoc이 아주 적합합니다.

ReDoc은 제공된 OpenAPI 사양을 기반으로 예상 응답, 매개변수 및 데이터 유형을 포함하는 콘텐츠를 자동으로 생성한다는 점에 주목할 필요가 있습니다. 이는 상호 작용성보다 최적화된 내장 문서 지원을 우선시하는 프로젝트에 적합합니다.

옵션 3: NSwag – 문서화 + 코드 생성

다음으로 Tim은 NSwag라는 유연하고 기능이 풍부한 도구에 대해 자세히 살펴봅니다. NSwag는 API 문서화뿐만 아니라 C#, TypeScript 등 다양한 언어로 클라이언트용 코드를 생성할 수도 있습니다. NSwag.AspNetCore NuGet 패키지를 설치한 후, 그는 Swagger와 유사한 인터페이스를 설정하고 이를 동일한 JSON 엔드포인트에 매핑합니다.

Tim은 NSwag가 Swagger 사양과 OpenAPI 표준을 모두 지원하므로 개발자가 선호하는 형식을 선택할 수 있다고 설명합니다. 사용자 인터페이스는 Swagger와 비슷해 보일 수 있지만, NSwag의 진가는 외부 도구 라이브러리와 고급 기능(예: 자동 클라이언트 생성)에서 드러납니다.

그는 NSwag의 코드 생성 기능이 특히 여러 서비스나 외부 도구를 사용하는 프로젝트에서 API 통합 시 수작업을 줄이는 데 도움이 된다고 지적합니다. 이는 견고한 클라이언트-서버 통신을 구축하는 팀에게 강력한 솔루션입니다.

옵션 4: 스케일러 – 팀이 API 테스트에 가장 선호하는 도구

팀은 모든 옵션 중에서 개인적으로 가장 좋아하는 것으로 Scaler UI를 소개하며, Postman과 브라우저 기반 문서화 기능을 결합한 것이라고 설명합니다. Scaler.AspNetCore 패키지를 추가한 후에는 인터페이스를 활성화하기 위해 단 한 줄의 코드(app.MapScalerApiReference())만 필요합니다.

Scaler는 쿼리 매개변수, 헤더 및 쿠키를 사용한 요청 실행을 포함하여 완전한 상호 작용을 지원합니다. 이 서비스의 차별점은 실시간 피드백입니다. 응답 시간, 헤더 및 결과 페이로드를 즉시 반환합니다.

Scaler의 두드러진 특징 중 하나는 다양한 언어(PHP, Node, Python, HttpClient 및 RestSharp를 통한 C#)에 대한 curl 명령과 클라이언트 코드 스니펫을 생성할 수 있다는 점입니다. 팀은 개발 중에 API 호출을 빠르게 복사하고 붙여넣는 데 이 기능이 특히 유용하다고 생각합니다.

Scaler는 밝은 모드와 어두운 모드 간 전환 기능도 제공하여 사용자 친화적인 API 문서화 플랫폼이지만, 향후 개선의 여지는 더 있습니다. 오픈 소스 API 플랫폼인 Scaler는 활발한 유지 관리와 높은 커뮤니티 관심 덕분에 지속적으로 발전하고 있습니다.

결론: 다양한 선택지는 유연성을 가져다줍니다

영상 말미에서 팀은 .NET 웹 템플릿에서 Swagger UI를 제거하는 것이 퇴보처럼 보일 수 있지만, 실제로는 현대적이고 더욱 맞춤화된 솔루션을 도입할 수 있는 기회라고 강조합니다. 이러한 변화는 기능이 더욱 모듈화되고 특정 기능에 집중되는 마이크로소프트의 빠른 출시 주기와 일맥상통합니다.

이제 OpenAPI 지원은 엄격한 네이티브 구현 방식이 아닌, 핵심적인 지원 기능으로 자리 잡았습니다. 프로젝트 요구 사항에 따라 Scaler를 사용한 대화형 테스트, NSwag를 사용한 클라이언트 코드 생성, ReDoc을 사용한 깔끔한 출력 등 다양한 도구를 자유롭게 조합하여 사용할 수 있습니다.

Tim은 개발자들이 이러한 도구들을 살펴보고, 자신의 워크플로에 맞는 도구를 찾아보고, 나아가 여러 환경에 맞춰 다양한 UI를 사용하는 것(예: 개발용 UI와 공개 문서용 UI)을 고려해 보도록 권장합니다. 이러한 모든 옵션이 OpenAPI 및 Swagger 사양을 지원한다는 사실은 특정 공급업체나 워크플로에 종속되지 않는다는 것을 의미합니다.

결론

.NET 9에서 Swagger UI가 기본값에서 제외됨에 따라 개발자는 이제 OpenAPI 문서화 요구 사항에 가장 적합한 도구를 자유롭게 선택할 수 있게 되었습니다. HTTP API를 문서화하든, 외부 도구를 제공하든, 내부 개발을 지원하든, 목표에 맞는 솔루션이 있습니다.

Swagger UI, ReDoc, NSwag, Scaler와 같은 도구를 사용하면 API 문서화 및 테스트가 그 어느 때보다 사용자 정의가 가능하고 개발자 친화적입니다. 팀 코리가 자신의 비디오 에서 보여주듯이, 필요한 것은 몇 가지 패키지, 몇 줄의 코드, 그리고 애플리케이션과 팀에 가장 적합한 도구를 탐색하려는 의지만 있으면 됩니다.