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

Mike Wassonby Mike Wasson

코드를 사용 하 여이 자습서에는 ASP.NET에서 ASP.NET Web API에 대 한 도움말 페이지를 만드는 방법을 보여 줍니다 4.x 합니다.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 및 웹 도구 2012.2 업데이트합니다.Install ASP.NET and Web Tools 2012.2 Update. 이 업데이트는 Web API 프로젝트 템플릿으로 도움말 페이지를 통합합니다.This update integrates help pages into the Web API project template.

새 ASP.NET MVC 4 프로젝트를 만들고으로, Web API 프로젝트 템플릿을 선택 합니다.Next, create a new ASP.NET MVC 4 project and select the Web API project template. 프로젝트 템플릿이 라는 API 예제 컨트롤러를 만듭니다 ValuesController합니다.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. 사용 하 여 테이블 항목을 동적으로 생성 합니다 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. "Description" 열에는 각 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

기존 Web API 프로젝트에 NuGet 패키지 관리자를 사용 하 여 도움말 페이지를 추가할 수 있습니다.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.

이 명령은 필요한 어셈블리를 설치 하 고 (영역/HelpPage 폴더에 있음) 도움말 페이지에 대 한 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 파일에 다음 코드를 추가 합니다 응용 프로그램_시작 메서드를 사용할 수 없는 아직 경우: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. 이 기능을 사용 하려면 영역/HelpPage/앱 파일을 엽니다_Start/HelpPageConfig.cs 다음 줄을 주석 처리 제거 합니다.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. 편집 상자에 입력 "앱_Data/XmlDocument.xml"입니다.In the edit box, type "App_Data/XmlDocument.xml".

다음으로 코드를 열고는 ValuesController /Controllers/ValuesController.cs에 정의 된 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

팁: 메서드 위의 줄에 캐럿을 배치 하 고 3 개의 슬래시를 입력 하는 경우 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

도움말 페이지의 맨 위에 빌드됩니다 합니다 ApiExplorer Web API 프레임 워크에 참가 하는 클래스입니다.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 포함 된 ApiDescription API를 설명 하는 합니다.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/Products 가져오기GET /api/Products
  • 가져오기/a p i/제품 / {id}GET /api/Products/{id}
  • Api 제품 게시POST /api/Products

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

API를 숨기려면를 ApiExplorer를 추가 합니다 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. 도움말 페이지 라이브러리에서 제공 하는 앞서 살펴본 대로 IDocumentationProvider 는 XML 문서 문자열에서 설명서를 가져옵니다.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. 호출 하 고 연결 하는 SetDocumentationProvider 에 정의 된 확장 메서드, HelpPageConfigurationExtensionsTo 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 Lin 기록한:Yao Huang Lin has written some great blog posts to get you thinking out of the box: