Swagger를 사용하여 개발하다 보면 API에 대한 좀더 자세한 설명을 제공 하고 싶을 때가 있는데, 스팩화면을 별도로 개발하거나 문서를 작성하지 않고 C#코드에 추가한 XML주석을 활용하여 Swagger UI에 바로 세부 메타 데이터 정보 추가 할 수 있다.
먼저, C# 코드의 각 Class, Method, Properties 등에 XML 주석을 추가 작성해 보자.
(TIP, 정의 코드 위에서 ‘/(Slash)’를 연속 3번 누르면 자동으로 XML 테그를 생성해준다.)
이제 작성된 XML 코드들이 문서(파일)로 저장 될 수 있도록 프로젝트 환경설정에 설정 하도록 한다.
프로젝트 속성에서 빌드 메뉴를 살펴 보면 출력 관련 설정하는 영역을 확인 할 수 있다.
XML 문서 파일 체크 박스를 그림과 같이 체크한다, 설정(체크) 하면 우측에 경로가 기본값으로 셋팅 되며, 해당 경로 값을 복사해 둔다.
(원하는 경로가 있다면 변경해도 되지만, 기본값 쓰는 것을 권장한다.)
다음으로, 저장된 XML 문서 파일을 Swagger에서 열어서 화면에 표시 할 수 있도록 설정 해야 한다.
SwaggerConfig.cs을 열어 다음과 같이 코드를 추가 한다.
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerFramework.XML"
, System.AppDomain.CurrentDomain.BaseDirectory));
})
/*.......... 생략 ............*/
(복사한 경로값으로 “\bin\SwaggerFramework.XML”부분을 변경하여 설정 한다.)
이제, 설정이 완료 되었으니 프로젝트를 실행 시켜 어떻게 나오는지 확인해 보자.
Swagger UI를 확인해 보면 위 XML코드를 작성한 내용이 태그 이름에 따라 화면에 나타는 것을 확인 할 수 있다.
이와 같이, Swagger UI에서 C#코드의 사용자 정의 XML(주석)을 사용하여 API들에 대한 설명들을 메타 데이터 표현할 수 있도록 함으로써, 추가적인 별다른 노력 없이 좀 더 자세한 API 스팩 문서를 작성 및 제공 할 수 있다.
THE NEWTH 