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

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";
}

이제 응용 프로그램을 다시 빌드하고 실행한 다음, 도움말 페이지로 이동해봅니다. 그러면, 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은 사고의 틀을 깰 수 있게 해주는 몇 가지 멋진 블로그 포스트를 공개했습니다:

• Adding a simple Test Client to ASP.NET Web API Help Page
• Making ASP.NET Web API Help Page work on self-hosted services
• Design-time generation of help page (or client) for ASP.NET Web API
• Advanced Help Page customizations