ASP.NET Web API에 대 한 도움말 페이지 만들기Creating Help Pages for ASP.NET Web API

Mike Wassonby Mike Wasson

이 자습서에서는 ASP.NET 4.x의 ASP.NET Web API에 대 한 도움말 페이지를 만드는 방법을 보여 줍니다.This tutorial with code shows how to create help pages for ASP.NET Web API in ASP.NET 4.x.

Web API를 만들 때 다른 개발자가 API를 호출 하는 방법을 알 수 있도록 도움말 페이지를 만드는 것이 유용한 경우가 많습니다.When you create a web API, it is often useful to create a help page, so that other developers will know how to call your API. 모든 설명서를 수동으로 만들 수 있지만 최대한 자동 생성 하는 것이 좋습니다.You could create all of the documentation manually, but it is better to autogenerate as much as possible. 이 작업을 더 쉽게 수행 하기 위해 ASP.NET Web API는 런타임에 도움말 페이지를 자동으로 생성 하기 위한 라이브러리를 제공 합니다.To make this task easier, ASP.NET Web API provides a library for auto-generating help pages at run time.

API 도움말 페이지 만들기Creating API Help Pages

ASP.NET 및 Web Tools 2012.2 업데이트를 설치 합니다.Install ASP.NET and Web Tools 2012.2 Update. 이 업데이트는 웹 API 프로젝트 템플릿에 도움말 페이지를 통합 합니다.This update integrates help pages into the Web API project template.

다음으로, 새 ASP.NET MVC 4 프로젝트를 만들고 웹 API 프로젝트 템플릿을 선택 합니다.Next, create a new ASP.NET MVC 4 project and select the Web API project template. 프로젝트 템플릿은 ValuesController이라는 예제 API 컨트롤러를 만듭니다.The project template creates an example API controller named ValuesController. 템플릿은 또한 API 도움말 페이지를 만듭니다.The template also creates the API help pages. 도움말 페이지의 모든 코드 파일은 프로젝트의 영역 폴더에 배치 됩니다.All of the code files for the help page are placed in the Areas folder of the project.

응용 프로그램을 실행할 때 홈 페이지에는 API 도움말 페이지에 대 한 링크가 포함 되어 있습니다.When you run the application, the home page contains a link to the API help page. 홈 페이지에서 상대 경로는/Help.From the home page, the relative path is /Help.

이 링크를 누르면 API 요약 페이지가 표시 됩니다.This link brings you to an API summary page.

이 페이지에 대 한 MVC 뷰는 Areas/HelpPage/Views/Help/Index. cshtml에 정의 되어 있습니다.The MVC view for this page is defined in Areas/HelpPage/Views/Help/Index.cshtml. 이 페이지를 편집 하 여 레이아웃, 소개, 제목, 스타일 등을 수정할 수 있습니다.You can edit this page to modify the layout, introduction, title, styles, and so forth.

페이지의 주요 부분은 컨트롤러 별로 그룹화 된 Api의 테이블입니다.The main part of the page is a table of APIs, grouped by controller. Table 항목은 Iapiexplorer 인터페이스를 사용 하 여 동적으로 생성 됩니다.The table entries are generated dynamically, using the IApiExplorer interface. 이 인터페이스에 대해서는 나중에 자세히 설명 합니다. 새 API 컨트롤러를 추가 하는 경우 테이블은 런타임에 자동으로 업데이트 됩니다.(I'll talk more about this interface later.) If you add a new API controller, the table is automatically updated at run time.

"API" 열에는 HTTP 메서드 및 상대 URI가 나열 됩니다.The "API" column lists the HTTP method and relative URI. "설명" 열에는 각 API에 대 한 설명서가 포함 되어 있습니다.The "Description" column contains documentation for each API. 처음에는 설명서가 자리 표시자 텍스트입니다.Initially, the documentation is just placeholder text. 다음 섹션에서는 XML 주석에서 설명서를 추가 하는 방법을 보여 줍니다.In the next section, I'll show you how to add documentation from XML comments.

각 API에는 예제 요청 및 응답 본문을 포함 하 여 보다 자세한 정보를 포함 하는 페이지에 대 한 링크가 있습니다.Each API has a link to a page with more detailed information, including example request and response bodies.

기존 프로젝트에 도움말 페이지 추가Adding Help Pages to an Existing Project

NuGet 패키지 관리자를 사용 하 여 기존 Web API 프로젝트에 도움말 페이지를 추가할 수 있습니다.You can add help pages to an existing Web API project by using NuGet Package Manager. 이 옵션은 "Web API" 템플릿과 다른 프로젝트 템플릿에서 시작 하는 데 유용 합니다.This option is useful you start from a different project template than the "Web API" template.

도구 메뉴에서 NuGet 패키지 관리자를 선택한 다음 패키지 관리자 콘솔을 선택 합니다.From the Tools menu, select NuGet Package Manager, and then select Package Manager Console. 패키지 관리자 콘솔 창에서 다음 명령 중 하나를 입력 합니다.In the Package Manager Console window, type one of the following commands:

C# 응용 프로그램의 경우: Install-Package Microsoft.AspNet.WebApi.HelpPageFor a C# application: Install-Package Microsoft.AspNet.WebApi.HelpPage

Visual Basic 응용 프로그램의 경우: Install-Package Microsoft.AspNet.WebApi.HelpPage.VBFor a Visual Basic application: Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

에 C# 는 두 개의 패키지가 있습니다. 하나는 Visual Basic입니다.There are two packages, one for C# and one for Visual Basic. 프로젝트와 일치 하는 항목을 사용 해야 합니다.Make sure to use the one that matches your project.

이 명령은 필요한 어셈블리를 설치 하 고 영역/도움말 페이지 폴더에 있는 도움말 페이지에 대 한 MVC 뷰를 추가 합니다.This command installs the necessary assemblies and adds the MVC views for the help pages (located in the Areas/HelpPage folder). 도움말 페이지에 대 한 링크를 수동으로 추가 해야 합니다.You'll need to manually add a link to the Help page. URI는/Help.The URI is /Help. Razor 뷰에서 링크를 만들려면 다음을 추가 합니다.To create a link in a razor view, add the following:

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

또한 영역을 등록 해야 합니다.Also, make sure to register areas. Global.asax 파일에서 다음 코드를 응용 프로그램_Start 메서드에 추가 합니다 (아직 없는 경우).In the Global.asax file, add the following code to the Application_Start method, if it is not there already:

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

API 설명서 추가Adding API Documentation

기본적으로 도움말 페이지에는 설명서에 대 한 자리 표시자 문자열이 있습니다.By default, the help pages have placeholder strings for documentation. XML 문서 주석을 사용 하 여 설명서를 만들 수 있습니다.You can use XML documentation comments to create the documentation. 이 기능을 사용 하도록 설정 하려면 파일 영역/도움말 페이지/앱_Start/HelpPageConfig을 열고 다음 줄의 주석 처리를 제거 합니다.To enable this feature, open the file Areas/HelpPage/App_Start/HelpPageConfig.cs and uncomment the following line:

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

이제 XML 설명서를 사용 하도록 설정 합니다.Now enable XML documentation. 솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭 하 고 속성을 선택 합니다.In Solution Explorer, right-click the project and select Properties. 빌드 페이지를 선택 합니다.Select the Build page.

출력에서 XML 문서 파일을 선택 합니다.Under Output, check XML documentation file. 편집 상자에 "App_Data/XmlDocument .xml"을 입력 합니다.In the edit box, type "App_Data/XmlDocument.xml".

그런 다음/Controllers/ValuesController.cs.에 정의 된 ValuesController API 컨트롤러에 대 한 코드를 엽니다.Next, open the code for the ValuesController API controller, which is defined in /Controllers/ValuesController.cs. 컨트롤러 메서드에 몇 가지 설명서 주석을 추가 합니다.Add some documentation comments to the controller methods. 다음은 그 예입니다.For example:

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

Note

팁: 메서드 위의 줄에 캐럿을 배치 하 고 세 개의 슬래시를 입력 하면 Visual Studio에서 XML 요소를 자동으로 삽입 합니다.Tip: If you position the caret on the line above the method and type three forward slashes, Visual Studio automatically inserts the XML elements. 그런 다음 공백을 입력할 수 있습니다.Then you can fill in the blanks.

이제 응용 프로그램을 빌드 및 실행 하 고 도움말 페이지로 이동 합니다.Now build and run the application again, and navigate to the help pages. 설명서 문자열은 API 테이블에 표시 되어야 합니다.The documentation strings should appear in the API table.

도움말 페이지는 런타임에 XML 파일에서 문자열을 읽습니다.The help page reads the strings from the XML file at run time. 응용 프로그램을 배포할 때 XML 파일을 배포 해야 합니다.(When you deploy the application, make sure to deploy the XML file.)

내부적으로Under the Hood

도움말 페이지는 웹 API 프레임 워크의 일부인 Apiexplorer 클래스 위에 빌드됩니다.The help pages are built on top of the ApiExplorer class, which is part of the Web API framework. Apiexplorer 클래스는 도움말 페이지를 만들기 위한 원시 자료를 제공 합니다.The ApiExplorer class provides the raw material for creating a help page. 각 API에 대해 Apiexplorer 는 api를 설명 하는 apiexplorer 을 포함 합니다.For each API, ApiExplorer contains an ApiDescription that describes the API. 이러한 목적을 위해 "API"는 HTTP 메서드와 상대 URI의 조합으로 정의 됩니다.For this purpose, an "API" is defined as the combination of HTTP method and relative URI. 예를 들어, 다음은 몇 가지 고유한 Api입니다.For example, here are some distinct APIs:

  • /Api/제품 가져오기GET /api/Products
  • /Api/Products/{id} 가져오기GET /api/Products/{id}
  • 게시/a n o/제품POST /api/Products

컨트롤러 작업에서 여러 HTTP 메서드를 지 원하는 경우 Apiexplorer 는 각 메서드를 고유한 API로 처리 합니다.If a controller action supports multiple HTTP methods, the ApiExplorer treats each method as a distinct API.

Apiexplorer에서 API를 숨기려면 ApiExplorerSettings 특성을 작업에 추가 하 고 ignoreapi 를 true로 설정 합니다.To hide an API from the ApiExplorer, add the ApiExplorerSettings attribute to the action and set IgnoreApi to true.

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

컨트롤러에이 특성을 추가 하 여 전체 컨트롤러를 제외할 수도 있습니다.You can also add this attribute to the controller, to exclude the entire controller.

ApiExplorer 클래스는 Idocumentationprovider 인터페이스에서 설명서 문자열을 가져옵니다.The ApiExplorer class gets documentation strings from the IDocumentationProvider interface. 앞서 살펴본 것 처럼 도움말 페이지 라이브러리는 XML 문서 문자열에서 설명서를 가져오는 Idocumentationprovider 를 제공 합니다.As you saw earlier, the Help Pages library provides an IDocumentationProvider that gets documentation from XML documentation strings. 코드는/Areas/HelpPage/XmlDocumentationProvider.cs.에 있습니다.The code is located in /Areas/HelpPage/XmlDocumentationProvider.cs. 고유한 Idocumentationprovider를 작성 하 여 다른 원본에서 설명서를 가져올 수 있습니다.You can get documentation from another source by writing your own IDocumentationProvider. 연결 하려면 HelpPageConfigurationExtensions 에 정의 된 Setdocumentationprovider 확장 메서드를 호출 합니다.To wire it up, call the SetDocumentationProvider extension method, defined in HelpPageConfigurationExtensions

Apiexplorer 는 자동으로 Idocumentationprovider 인터페이스를 호출 하 여 각 API에 대 한 설명서 문자열을 가져옵니다.ApiExplorer automatically calls into the IDocumentationProvider interface to get documentation strings for each API. ApidescriptionApiParameterDescription 개체의 설명서 속성에 저장 합니다.It stores them in the Documentation property of the ApiDescription and ApiParameterDescription objects.

다음 단계Next Steps

여기에 표시 된 도움말 페이지로 제한 되지 않습니다.You aren't limited to the help pages shown here. 실제로 Apiexplorer 는 도움말 페이지를 만드는 것으로 제한 되지 않습니다.In fact, ApiExplorer is not limited to creating help pages. Yao Huang 링크는 다음과 같은 몇 가지 유용한 블로그 게시물을 작성 하 여이에 대해 알아 볼 수 있습니다.Yao Huang Lin has written some great blog posts to get you thinking out of the box: