ASP.NET Web API 대한 도움말 페이지 만들기

아티클
06/16/2023

코드가 포함된 이 자습서에서는 ASP.NET 4.x에서 ASP.NET Web API 대한 도움말 페이지를 만드는 방법을 보여줍니다.

웹 API를 만들 때 다른 개발자가 API를 호출하는 방법을 알 수 있도록 도움말 페이지를 만드는 것이 유용한 경우가 많습니다. 모든 설명서를 수동으로 만들 수 있지만 가능한 한 많이 자동 생성하는 것이 좋습니다. 이 작업을 더 쉽게 수행하기 위해 ASP.NET Web API 런타임에 도움말 페이지를 자동으로 생성하기 위한 라이브러리를 제공합니다.

선택할 수 있는 API 제품과 해당 설명을 보여 주는 ASP dot NET A P I 도움말 페이지의 스크린샷.

API 도움말 페이지 만들기

ASP.NET 및 Web Tools 2012.2 업데이트를 설치합니다. 이 업데이트는 도움말 페이지를 Web API 프로젝트 템플릿에 통합합니다.

다음으로 새 ASP.NET MVC 4 프로젝트를 만들고 Web API 프로젝트 템플릿을 선택합니다. 프로젝트 템플릿은 라는 ValuesController예제 API 컨트롤러를 만듭니다. 템플릿은 API 도움말 페이지도 만듭니다. 도움말 페이지의 모든 코드 파일은 프로젝트의 Areas 폴더에 배치됩니다.

영역 및 도움말 페이지 폴더를 순환하는 Web API 프로젝트 템플릿의 메뉴 옵션 스크린샷

애플리케이션을 실행할 때 홈 페이지에는 API 도움말 페이지에 대한 링크가 포함됩니다. 홈페이지에서 상대 경로는 /Help입니다.

도움말 페이지에 대한 링크를 여는 클릭 가능한 AP 문자를 가리키는 홈 페이지의 스크린샷.

이 링크를 통해 API 요약 페이지로 이동합니다.

다른 AP I 값과 해당 설명을 보여 주는 AP I 요약 도움말 페이지의 스크린샷

이 페이지의 MVC 보기는 Areas/HelpPage/Views/Help/Index.cshtml에 정의되어 있습니다. 이 페이지를 편집하여 레이아웃, 소개, 제목, 스타일 등을 수정할 수 있습니다.

페이지의 기본 부분은 컨트롤러별로 그룹화된 API 테이블입니다. 테이블 항목은 IApiExplorer 인터페이스를 사용하여 동적으로 생성됩니다. (나중에 이 인터페이스에 대해 자세히 설명하겠습니다.) 새 API 컨트롤러를 추가하면 런타임에 테이블이 자동으로 업데이트됩니다.

"API" 열에는 HTTP 메서드 및 상대 URI가 나열됩니다. "설명" 열에는 각 API에 대한 설명서가 포함되어 있습니다. 처음에는 설명서가 자리 표시자 텍스트일 뿐입니다. 다음 섹션에서는 XML 주석에서 설명서를 추가하는 방법을 보여 줍니다.

각 API에는 예제 요청 및 응답 본문을 포함하여 자세한 정보가 포함된 페이지에 대한 링크가 있습니다.

응답 정보 및 응답 본문 형식을 보여 주는 AP I 선택 값 중 하나의 스크린샷

기존 프로젝트에 도움말 페이지 추가

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"를 입력합니다.

출력 경로와 X ML 설명서 파일을 선택하는 옵션을 보여 주는 출력 대화 상자의 스크린샷

다음으로 /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 테이블에 표시됩니다.

AP I 값 및 설명의 설명서 문자열을 보여 주는 도움말 페이지의 AP I 테이블 스크린샷

도움말 페이지는 런타임에 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은 훌륭한 블로그 게시물을 작성하여 즉시 생각할 수 있도록 했습니다.

다음을 통해 공유