Swagger for ASP.NET WebAPI

여러분, 혹시 ' swagger'라는 단어를 들어본 적 있나요? 개발에 관심 있는 친구들이라면 한 번쯤 들어봤을 법한 이 단어가 요즘 개발자들 사이에서 아주 뜨겁다고 해요. 도대체 swagger가 무엇이고, 왜 개발자들이 여기에 열광하는 걸까요? 함께 알아봐요!

 

swagger는 한마디로 개발자들이 API라는 복잡한 것을 더 쉽고 편하게 다룰 수 있도록 돕는 강력한 도구랍니다. 웹사이트나 앱을 만들 때, 프론트엔드(눈에 보이는 부분)와 백엔드(데이터 처리 부분) 개발자들은 서로 약속된 방식으로 데이터를 주고받아야 하는데요. 이때 API가 그 약속의 역할을 하죠. swagger는 이 API의 구조를 한눈에 보여주고, 심지어 직접 테스트까지 해볼 수 있게 해줘요. 마치 복잡한 기계의 사용 설명서와 시뮬레이터를 동시에 제공하는 것과 같다고 할 수 있어요. 이런 도구가 있다면 프론트엔드와 백엔드 개발자들이 훨씬 더 빠르고 효율적으로 협업할 수 있겠죠?

 

'OpenAPI'와 'Swagger', 둘은 어떤 관계인가요?

" openapi? swagger? 이름이 왜 두 개나 있나요? 둘이 같은 건가요, 다른 건가요?" 하고 궁금해하는 친구들이 있을 거예요. 이 둘은 떼려야 뗄 수 없는 관계지만, 역할은 조금 다르답니다.

 

openapi는 restful api를 설명하기 위한 '설계도' 또는 '명세서'라고 생각하면 돼요. API가 어떤 기능을 하고, 어떤 데이터를 주고받아야 하는지 등을 표준화된 형식으로 정의해 놓은 문서 같은 것이죠. 마치 건물을 짓기 전에 만드는 상세한 설계도면과 같아요. 이 설계도에는 API의 엔드포인트(접근 주소), 필요한 파라미터(입력 값), 반환되는 데이터 모델 등이 자세히 적혀 있어요.

 

그렇다면 swagger는 무엇일까요? swagger는 바로 이 openapi설계도를 기반으로 작동하는 '도구 모음(Tooling)'이랍니다. 가장 대표적인 도구가 바로 ' swagger ui'예요. 이 swagger ui는 openapi설계도를 멋지고 시각적으로 보여주고, 개발자들이 직접 API를 테스트해볼 수 있도록 해주는 프로그램이에요. 쉽게 말해, openapi는 API의 '설계도'이고, swagger는 그 설계도를 '보고 상호작용할 수 있는 프로그램'이라고 이해하면 된답니다. 이제 둘의 관계가 명확해졌죠?

 

 

Swagger를 사용하면 개발이 얼마나 편해질까요?

swagger를 사용하면 개발 과정이 정말 놀랍도록 편해져요. 마치 마법 지팡이처럼 말이죠! 어떤 점들이 그렇게 편리한지 살펴볼까요?

 

가장 먼저, 자동화된 API 문서를 얻을 수 있다는 점이에요. 개발자들이 코드를 작성하면, swagger가 그 코드를 분석해서 항상 최신 상태의 API 문서를 자동으로 만들어줘요. 예전에는 개발자들이 API가 바뀔 때마다 일일이 문서를 수정해야 해서 번거롭고 실수도 많았지만, swagger덕분에 문서와 실제 API 사이에 불일치가 생길 걱정이 없답니다. 항상 정확하고 최신 정보를 담은 문서를 보면서 작업할 수 있으니 개발 효율이 쑥쑥 올라가겠죠?

 

다음으로 개발 생산성이 확 높아져요. 프론트엔드 개발자들은 백엔드 개발이 끝날 때까지 기다릴 필요 없이, swagger ui를 통해 API의 응답 구조를 미리 확인하고 가상의 데이터를 만들어서 개발을 진행할 수 있어요. 이렇게 되면 개발 일정을 단축하고, 여러 팀원이 동시에 작업할 수 있어서 전체적인 개발 속도가 빨라진답니다. 개발자들은 더 이상 서로를 기다리지 않고 각자 맡은 일에 집중할 수 있게 되는 거죠.

 

마지막으로 api 테스트 가 아주 간편해지고 커뮤니케이션이 명확해져요. swagger ui는 별도의 api 테스트도구(예: Postman) 없이도 브라우저에서 직접 파라미터를 입력하고 API를 호출해서 응답을 바로 확인할 수 있게 해줘요. 이것만으로도 테스트 시간을 크게 줄일 수 있어요. 또한, 개발팀, 기획팀, 품질관리(QA)팀 등 모든 관계자가 동일한 swagger문서를 보면서 API에 대해 소통할 수 있기 때문에 오해나 불필요한 논쟁을 줄이고, 커뮤니케이션 비용도 절감된답니다.

 

 

ASP.NET Web API에서 Swagger를 어떻게 사용할 수 있나요?

그럼 실제로 asp.net web api프로젝트에서 swagger를 사용하려면 어떻게 해야 할까요? 주로 두 가지 인기 있는 오픈소스 라이브러리가 사용돼요. 바로 swashbuckle 과 nswag 인데요. 각 라이브러리의 특징을 간단히 비교해볼게요.

 

특징	Swashbuckle	NSwag
주요 기능	Swagger UI 생성, API 문서 자동화	Swagger UI 생성, 강력한 코드 생성
설치/설정	간단하고 쉬움	ASP.NET Core 미들웨어, CLI, GUI 도구 지원
문서화	C# XML 주석 자동 연동	OpenAPI 명세 기반
코드 생성	제한적	C#, TypeScript 클라이언트 코드 자동 생성
커스터마이징	다양한 UI 및 인증 옵션 제공	유연한 통합 방식

 

Swashbuckle, 설치부터 사용까지 어렵지 않나요?

"설치하고 설정하는 게 복잡하면 어쩌지?" 하고 걱정할 필요 없어요. asp.net web api(.NET Framework) 환경에서 swashbuckle을 설치하고 사용하는 방법은 생각보다 간단하답니다.

 

먼저, visual studio의 패키지 관리자 콘솔에서 간단한 명령어를 실행해서 swashbuckle nuget 패키지를 설치해요. Install-Package swashbuckle 이 명령어 하나면 끝이에요.

 

 

패키지 설치가 완료되면, 프로젝트의 app_start 폴더에 swaggerconfig.cs라는 파일이 자동으로 생성된 것을 확인할 수 있을 거예요. 이 파일이 바로 swagger의 설정을 담당하는 파일이죠. 이제 swaggerconfig.cs 파일에 있는 Register 메서드에서 주석 처리된 부분을 찾아서 주석을 해제해주기만 하면 돼요. 이 부분을 통해 swagger를 활성화하고, 필요한 경우 xml 주석을 포함하도록 설정할 수 있답니다.

 

모든 설정이 끝났으면 프로젝트를 실행해보고, 웹 브라우저 주소창에 [기본 URL]/swagger를 입력해보세요. 그러면 멋진 swagger ui문서가 여러분을 반겨줄 거예요! 정말 간단하죠?