API를 개발 하다보면 자연스럽게 생기는 대표적인 고민이 바로 버전 관리 이다.
예를 들어
- 버전을 개별 기능(URL) 별로 관리 할 것인가? 아니면 개별 기능을 구룹화하여 구룹별로 할 것인가?
- 버전에 대한 URL 설계는 어떻게 할 것인가?
- 버전 관리를 한다면 구버전 지원은 어떻게 할 것인가?
등등…
이러한 고민들을 Swagger의 MultipleApiVersions을 이용하여 멀티 버전을 설정하면 해결 할 수 있다.
API APP 프로젝트를 만들면 다음과 같은 경로에 SwaggerConfig.cs라는 파일을 볼 수 있다. (위차: ~/App_Start/SwaggerConfig.cs)
클릭해서 열어보면 대략 Line:35 정도에 c.SingleApiVersion 이라는 것이 기본으로 설정되어 있는 것을 볼 수 있는데 이것은 API APP프로젝트를 처음 만들면 API 샘플(~/Controller/ValueController.cs) 1개가 등록 되어 있기때문에 멀티 버전 관리를 할 수 있는게 없기 때문이다.
멀티 버전을 관리 설정을 하기 전에 우선 간단히 아래 그림과 같이 2개의 API를 만들어 보도록 하겠다.
(프로젝트 샘플 소스를 가지고 실제 기능은 없고 단순히 호출 할 수 있는 Method만 만들었다. Student – ClassRoom: 학생 API / Teacher – Report : 선생님 API)
위와 같이 구성하면, 각각의 컨트롤러 파일의 Namespace는
Student : SwaggerFramework.Controllers.Student
Teacher : SwaggerFramework.Controllers.Teacher
로 설정 된 것을 확인 할 수 있다.
이제 위와 같이 설정된 Namespace를 가지고 API 버전을 구분 할 수 있도록 MultipleApiVersions를 설정해 보자.
앞서 언급한 SwaggerConfig.cs라는 파일을 열어 Line:35 정도에 있는 c.SingleApiVersion으로 이동하여, 해당 줄을 삭제(보통 주석 해두는 것이 좋다.)하고 아래와 같이 코드를 추가 하도록 한다.
//c.SingleApiVersion("v1", "SwaggerFramework");
c.MultipleApiVersions((apiDesc, targetApiVersion) =>
{
var controllerNamespace = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.FullName;
if(CultureInfo.InvariantCulture.CompareInfo.IndexOf(controllerNamespace, string.Format(".{0}.", targetApiVersion), CompareOptions.IgnoreCase) >= 0)
{
return true;
}
return false;
},(vc) =>
{
vc.Version("Student", "Student API v1");
vc.Version("Teacher", "Teacher API v1");
});
위와 같이 설정하면 각 Namespace(Student, Teacher)이름에 따라서 버전이 구분을 할 수 있다.
실제로 구분이 되는지 프로젝트를 실행 해보면 다음 그림과 같이 API가 Namespace 별로 구분되어 확인 할 수 있다.
Swagger Explore 창에 Namespace를 이용하여 검색해보면, SwaggerConfig.cs에 설정해 둔 각 API설명과 해당 Namespace를 가지고 있는 API 기능을 구별하여 확인 할 수 있다.
(Explore 검색 예시 – http://{ Domain Path }/swagger/docs/[ Studnet | Teacher ])
이와 같이 Swagger의 환경 설정에서 Namespace를 이용하면 간단히 API를 버전별로 구분(그룹화)하여 제공 할 수 있기 때문에 버전관리를 쉽게 할 수 있다.
THE NEWTH 