코드가 포함된 이 자습서에서는 ASP.NET 4.x에서 ASP.NET Web API 대한 도움말 페이지를 만드는 방법을 보여줍니다.
웹 API를 만들 때 다른 개발자가 API를 호출하는 방법을 알 수 있도록 도움말 페이지를 만드는 것이 유용한 경우가 많습니다. 모든 설명서를 수동으로 만들 수 있지만 가능한 한 많이 자동 생성하는 것이 좋습니다. 이 작업을 더 쉽게 수행하기 위해 ASP.NET Web API 런타임에 도움말 페이지를 자동으로 생성하기 위한 라이브러리를 제공합니다.
API 도움말 페이지 만들기
ASP.NET 및 Web Tools 2012.2 업데이트를 설치합니다. 이 업데이트는 도움말 페이지를 Web API 프로젝트 템플릿에 통합합니다.
다음으로 새 ASP.NET MVC 4 프로젝트를 만들고 Web API 프로젝트 템플릿을 선택합니다. 프로젝트 템플릿은 라는 ValuesController예제 API 컨트롤러를 만듭니다. 템플릿은 API 도움말 페이지도 만듭니다. 도움말 페이지의 모든 코드 파일은 프로젝트의 Areas 폴더에 배치됩니다.
애플리케이션을 실행할 때 홈 페이지에는 API 도움말 페이지에 대한 링크가 포함됩니다. 홈페이지에서 상대 경로는 /Help입니다.
이 링크를 통해 API 요약 페이지로 이동합니다.
이 페이지의 MVC 보기는 Areas/HelpPage/Views/Help/Index.cshtml에 정의되어 있습니다. 이 페이지를 편집하여 레이아웃, 소개, 제목, 스타일 등을 수정할 수 있습니다.
페이지의 기본 부분은 컨트롤러별로 그룹화된 API 테이블입니다. 테이블 항목은 IApiExplorer 인터페이스를 사용하여 동적으로 생성됩니다. (나중에 이 인터페이스에 대해 자세히 설명하겠습니다.) 새 API 컨트롤러를 추가하면 런타임에 테이블이 자동으로 업데이트됩니다.
"API" 열에는 HTTP 메서드 및 상대 URI가 나열됩니다. "설명" 열에는 각 API에 대한 설명서가 포함되어 있습니다. 처음에는 설명서가 자리 표시자 텍스트일 뿐입니다. 다음 섹션에서는 XML 주석에서 설명서를 추가하는 방법을 보여 줍니다.
각 API에는 예제 요청 및 응답 본문을 포함하여 자세한 정보가 포함된 페이지에 대한 링크가 있습니다.
기존 프로젝트에 도움말 페이지 추가
NuGet 패키지 관리자를 사용하여 기존 Web API 프로젝트에 도움말 페이지를 추가할 수 있습니다. 이 옵션은 "Web API" 템플릿과 다른 프로젝트 템플릿에서 시작하는 데 유용합니다.
도구 메뉴에서 NuGet 패키지 관리자를 선택한 다음 패키지 관리자 콘솔을 선택합니다. 패키지 관리자 콘솔 창에서 다음 명령 중 하나를 입력합니다.
C# 애플리케이션의 경우:Install-Package Microsoft.AspNet.WebApi.HelpPage
Visual Basic 애플리케이션의 경우:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
C#용 패키지와 Visual Basic용 패키지 두 가지가 있습니다. 프로젝트와 일치하는 항목을 사용해야 합니다.
이 명령은 필요한 어셈블리를 설치하고 도움말 페이지에 대한 MVC 보기를 추가합니다(Areas/HelpPage 폴더에 있음). 도움말 페이지에 대한 링크를 수동으로 추가해야 합니다. URI는 /Help입니다. Razor 보기에서 링크를 만들려면 다음을 추가합니다.
@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)
또한 영역을 등록해야 합니다. Global.asax 파일에서 아직 없는 경우 Application_Start 메서드에 다음 코드를 추가합니다.
protected void Application_Start()
{
// Add this code, if not present.
AreaRegistration.RegisterAllAreas();
// ...
}
API 설명서 추가
기본적으로 도움말 페이지에는 설명서에 대한 자리 표시자 문자열이 있습니다. XML 설명서 주석을 사용하여 설명서를 만들 수 있습니다. 이 기능을 사용하도록 설정하려면 Areas/HelpPage/App_Start/HelpPageConfig.cs 파일을 열고 다음 줄의 주석 처리를 제거합니다.
config.SetDocumentationProvider(new XmlDocumentationProvider(
HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
이제 XML 설명서를 사용하도록 설정합니다. 솔루션 탐색기 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다. 빌드 페이지를 선택합니다.
출력에서 XML 설명서 파일을 검사. 편집 상자에 "App_Data/XmlDocument.xml"를 입력합니다.
다음으로 /Controllers/ValuesController.cs에 정의된 API 컨트롤러에 대한 ValuesController 코드를 엽니다. 컨트롤러 메서드에 몇 가지 설명서 주석을 추가합니다. 예:
/// <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 요소를 자동으로 삽입합니다. 그런 다음 공백을 채울 수 있습니다.
이제 애플리케이션을 빌드하고 다시 실행하고 도움말 페이지로 이동합니다. 설명서 문자열은 API 테이블에 표시됩니다.
도움말 페이지는 런타임에 XML 파일에서 문자열을 읽습니다. (애플리케이션을 배포할 때 XML 파일을 배포해야 합니다.)
후드 아래
도움말 페이지는 Web API 프레임워크의 일부인 ApiExplorer 클래스를 기반으로 빌드됩니다. ApiExplorer 클래스는 도움말 페이지를 만들기 위한 원료를 제공합니다. 각 API에 대해 ApiExplorer 에는 API를 설명하는 ApiDescription 이 포함되어 있습니다. 이를 위해 "API"는 HTTP 메서드와 상대 URI의 조합으로 정의됩니다. 예를 들어 몇 가지 고유한 API는 다음과 같습니다.
- GET /api/Products
- GET /api/Products/{id}
- POST /api/Products
컨트롤러 작업이 여러 HTTP 메서드를 지원하는 경우 ApiExplorer 는 각 메서드를 고유한 API로 처리합니다.
ApiExplorer에서 API를 숨기려면 ApiExplorerSettings 특성을 작업에 추가하고 IgnoreApi를 true로 설정합니다.
[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) { }
컨트롤러에 이 특성을 추가하여 전체 컨트롤러를 제외할 수도 있습니다.
ApiExplorer 클래스는 IDocumentationProvider 인터페이스에서 설명서 문자열을 가져옵니다. 앞에서 보았듯이 도움말 페이지 라이브러리는 XML 설명서 문자열에서 설명서를 가져오는 IDocumentationProvider 를 제공합니다. 코드는 /Areas/HelpPage/XmlDocumentationProvider.cs에 있습니다. 고유한 IDocumentationProvider를 작성하여 다른 원본에서 설명서를 가져올 수 있습니다. 연결하려면 HelpPageConfigurationExtensions에 정의된 SetDocumentationProvider 확장 메서드를 호출합니다.
ApiExplorer 는 IDocumentationProvider 인터페이스를 자동으로 호출하여 각 API에 대한 설명서 문자열을 가져옵니다. ApiDescription 및 ApiParameterDescription 개체의 Documentation 속성에 저장합니다.
다음 단계
여기에 표시된 도움말 페이지로 제한되지 않습니다. 실제로 ApiExplorer 는 도움말 페이지를 만드는 데만 국한되지 않습니다. Yao Huang Lin은 훌륭한 블로그 게시물을 작성하여 즉시 생각할 수 있도록 했습니다.