ASP.NET Web API 도움말 페이지 작성하기

등록일시: 2013-08-14 15:43,  수정일시: 2013-09-25 12:05
조회수: 7,042
이 문서는 ASP.NET Web API 기술을 널리 알리고자 하는 개인적인 취지로 제공되는 번역문서입니다. 이 문서에 대한 모든 저작권은 마이크로소프트에 있으며 요청이 있을 경우 언제라도 게시가 중단될 수 있습니다. 번역 내용에 오역이 존재할 수 있고 주석은 번역자 개인의 의견일 뿐이며 마이크로소프트는 이에 관한 어떠한 보장도 하지 않습니다. 번역이 완료된 이후에도 대상 제품 및 기술이 개선되거나 변경됨에 따라 원문의 내용도 변경되거나 보완되었을 수 있으므로 주의하시기 바랍니다.

Web API 개발 시, 다른 개발자들이 API의 사용법을 이해할 수 있도록 도움말 페이지를 함께 제공해주면 좋을 것입니다. 그리고, 이 도움말 페이지를 수작업으로 작성할 수도 있겠지만, 기왕이면 자동으로 생성하는 것이 더 편리할 것입니다.

ASP.NET Web API는 이런 작업들을 보다 손쉽게 처리할 수 있도록, 도움말 페이지를 런타임에 자동으로 생성할 수 있는 라이브러리를 제공해줍니다.

API 도움말 페이지 작성하기

먼저 ASP.NET and Web Tools 2012.2 Update 부터 설치해야 합니다. 이 업데이트는 Web API 프로젝트 템플릿에 도움말 페이지를 통합시켜 줍니다.

그런 다음, Web API 프로젝트 템플릿을 선택해서 새로운 ASP.NET MVC 4 프로젝트를 생성해보면, 프로젝트 템플릿에 의해서 ValuesController라는 이름의 예제 API 컨트롤러가 생성될 것입니다. 이때, API 도움말 페이지도 함께 생성되는데, 참고로 도움말 페이지와 관련된 모든 코드 파일들은 프로젝트의 Areas 폴더에 위치합니다.

응용 프로그램을 실행시켜 보면, 홈 페이지에 API 도움말 페이지로 이동하는 링크가 추가되어 있는 것을 확인할 수 있습니다.

이 링크를 클릭하면 API 요약 페이지로 이동하게 됩니다.

이 도움말 페이지의 MVC 뷰는 Areas/HelpPage/Views/Help/Index.cshtml에 정의되어 있습니다. 따라서, 이 뷰 페이지를 수정하면 레이아웃이나 소개글, 제목, 형태 등을 원하는 대로 자유롭게 변경할 수 있습니다.

이 페이지의 핵심 부분은 API들의 표로, 컨트롤러를 기준으로 분류되어 있습니다. 그리고, 표의 각 항목들은 IApiExplorer 인터페이스를 통해서 동적으로 생성됩니다. (잠시 뒤에 이 인터페이스에 관해서 다시 살펴볼 것입니다.) 그래서, 새로운 API 컨트롤러가 추가되면 실시간으로 표가 갱신됩니다.

이 표의 "API" 컬럼에는 HTTP 메서드와 관련 URI들의 조합이 나타납니다. 그리고, "Description" 컬럼에는 각 API에 대한 설명이 제공되는데, 처음에는 아주 기초적인 내용들만 나타납니다. 다음 절에서는 XML 주석을 이용해서 이 설명을 편집하는 방법을 살펴볼 것입니다.

각 API 컬럼에는 요청 예제나 응답 본문 등을 비롯한 보다 자세한 정보들을 제공해주는 페이지로 이동할 수 있는 링크가 걸려 있습니다.

노트: NuGet 패키지 관리자를 이용해서 도움말 페이지를 추가할 수도 있습니다. 이 방법은 "Web API" 템플릿 대신 다른 프로젝트 템플릿을 통해서 프로젝트를 시작한 경우에 유용합니다. 도움말 페이지 패키지를 설치하려면, 패키지 관리자 콘솔에서 다음 명령을 실행합니다:
Install-Package Microsoft.AspNet.WebApi.HelpPage

API 문서 추가하기

기본적으로 도움말 페이지는 아주 기초적인 설명만을 제공해줍니다. 그러나, XML 문서 주석을 활용해서 이 설명을 편집할 수도 있습니다. 이 기능을 활성화하려면 Areas/HelpPage/HelpPageAreaRegistration.cs 파일을 열고 다음 줄의 주석을 제거하십시요:

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

그런 다음, 이번에는 XML 문서를 활성화시켜야 합니다. Visual Studio의 솔루션 탐색기에서 마우스 오른쪽 버튼으로 프로젝트를 클릭한 다음, 속성 (Properties)을 선택하고, 빌드 (Build) 페이지를 선택합니다.

계속해서 출력 (Output) 영역 하위의 XML 문서 파일 (XML documentation file) 항목을 체크한 다음, 그 우측의 입력 박스에 "App_Data/XmlDocument.xml"이라고 입력합니다.

그런 다음, /Controllers/ValuesControler.cs 파일에 정의되어 있는 ValuesController API 컨트롤러의 코드를 열고, 컨트롤러 메서드에 약간의 설명 주석을 추가합니다. 다음은 그 사례입니다:

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}
    
/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}
: 캐럿을 메서드의 바로 위쪽 줄에 위치시킨 다음, 슬래시 문자를 세 개 입력하면 Visual Studio가 자동으로 XML 요소들을 삽입해줍니다. 그러면, 이 XML 요소들의 빈 칸을 채우기만 하면 됩니다.

이제 응용 프로그램을 다시 빌드하고 실행한 다음, 도움말 페이지로 이동해봅니다. 그러면, API 표에 주석에 입력한 내용들이 나타나는 것을 확인할 수 있습니다.

참고로 도움말 페이지는 런타임에 XML 파일로부터 문자열을 읽어들입니다. (따라서 응용 프로그램을 배포할 때, 이 XML 파일도 함께 배포해야만 합니다.)

내부 동작 방법

도움말 페이지는 Web API 프레임워크의 일부인 ApiExplorer 클래스를 기반으로 동작합니다. 이 ApiExplorer 클래스는 도움말 페이지를 생성하기 위한 기본적인 내용들을 제공해줍니다. ApiExplorer 클래스는 각 API들을 기술하는 ApiDescription 클래스들 갖고 있는데, 여기에서 말하는 "API"는 HTTP 메서드와 관련 URI의 조합으로 정의됩니다. 예를 들어서, 다음은 몇 가지 개별적인 API들의 목록입니다:

  • GET /api/Products
  • GET /api/Products/{id}
  • POST /api/Products

컨트롤러 액션이 복수의 HTTP 메서드들을 지원하는 경우, ApiExplorer 클래스는 각각의 HTTP 메서드들을 모두 별개의 API로 취급합니다.

그리고, 특정 API를 ApiExplorer 클래스로부터 감추려면 다음과 같이 ApiExplorerSettings 어트리뷰트를 액션에 추가하고 IgnoreApi 속성을 true로 설정하면 됩니다.

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

이 어트리뷰트는 컨트롤러에도 추가할 수 있으며, 그럴 경우 컨트롤러 전체가 숨겨집니다.

이 ApiExplorer 클래스는 IDocumentationProvider 인터페이스를 통해서 설명 문자열을 가져옵니다. 앞에서 살펴본 것처럼, 도움말 페이지 라이브러리는 XML 설명 문자열에서 설명을 가져오는 IDocumentationProvider 인터페이스를 제공해주며, 해당 코드는 /Areas/HelpPage/XmlDocumentationProvider.cs 파일에 존재합니다. 직접 IDocumentationProvider 인터페이스를 구현해서 다른 소스에서 설명을 가져올 수도 있는데, 이를 설정하려면 HelpPageConfigurationExtensions 클래스에 정의되어 있는 SetDocumentationProvider 확장 메서드를 호출하면 됩니다.

ApiExplorer 클래스는 각 API들에 대한 설명 문자열을 얻기 위해서 자동으로 IDocumentationProvider 인터페이스를 호출합니다. 그리고, 이를 ApiDescription 개체와 ApiParameterDescription 개체의 Documentation 속성에 저장합니다.

다음 단계

본 자습서에서 살펴본 도움말 페이지 관련 내용에만 얽매일 필요는 없습니다. 애초에, ApiExplorer 클래스 자체가 도움말 페이지 생성 용도로만 사용하기 위한 것도 아닙니다. 이를테면, Yao Huang Lin은 사고의 틀을 깰 수 있게 해주는 몇 가지 멋진 블로그 포스트를 공개했습니다: