WebAPI 도움말 페이지 - 반환 또는 매개 변수 모델/클래스 속성에 대한 설명서

Question

웹 API 2 (5.0)와 함께 웹 API 도움말 페이지를 사용하고 있습니다. 둘 다 최신 Nuget 패키지입니다. 도움말 문서에서 매개 변수이거나 HttpResponseMessage 본문에 반환 된 클래스에 대한 속성의 주석을 표시하고 싶습니다.

public HttpResponseMessage Post([FromBody] MyClassType1 myClass) 
{ 
    // Business logic removed for clarity 
    return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2()); 
} 

가 나는 위의 사후 조치에 대한 도움말 페이지에 표시 할 MyClassType1 및 MyClassType2에있는 XML 주석을 싶습니다

예를 들어,이 같은 컨트롤러 방법이있다.

내가 본 모든 곳에서 아직까지는 아직 지원되지 않는 것으로 보입니다. 그러나 ApiExplorer를 확장하여 XmlDocumentationProvider 등에 추가하여이 작업을 수행 할 수있는 사람이 있는지 궁금합니다.

생성 된 XML 파일에 주석과 속성이 포함되어 있으므로 수동으로 구문 분석 할 수 있습니다 (모든 매개 변수와 반환 형식은 MyAssemblyName.Models 네임 스페이스에 있으므로 생각할 수 있습니다.) 그 네임 스페이스로 시작하는 멤버 이름을 가진 XML 노드. 그러나 빌트인 웹 API 도움말 페이지에는 캐싱 기능이 일부 있기 때문에 필자는 이것을 어떻게 든 기존 기능과 통합하는 것을 선호한다. (단지 그것에 추가하자.)

@using System.Reflection 
@using System.Threading 
@using System.Web.Http.Description 
@using Regency.API.Services.Areas.HelpPage 
@model System.Collections.ObjectModel.Collection<ApiParameterDescription> 

<table class="help-page-table"> 
    <thead> 
     <tr><th>Name</th><th>Properties</th><th>Description</th><th>Additional information</th></tr> 
    </thead> 
    <tbody> 
     @foreach (ApiParameterDescription parameter in Model) 
     { 
      string parameterDocumentation = parameter.Documentation ?? "No documentation available."; 
      Type parameterType = parameter.ParameterDescriptor.ParameterType; 

      // Don't show CancellationToken because it's a special parameter 
      if (!typeof (CancellationToken).IsAssignableFrom(parameter.ParameterDescriptor.ParameterType)) 
      { 
       <tr> 
        <td class="parameter-name"><b>@parameter.Name</b></td> 
        <td class="parameter-properties"> 
         @foreach (PropertyInfo property in parameterType.GetProperties()) 
         { 
          <text>@property.Name : @property.PropertyType.GetFriendlyTypeName()</text> 
          <br/> 
         } 
        </td> 
        <td class="parameter-documentation"><pre>@parameterDocumentation</pre></td> 
        <td class="parameter-source"> 
         @switch(parameter.Source) 
         { 
          case ApiParameterSource.FromBody: 
           <p>Define this parameter in the request <b>body</b>.</p> 
           break; 
          case ApiParameterSource.FromUri: 
           <p>Define this parameter in the request <b>URI</b>.</p> 
           if (parameter.ParameterDescriptor.IsOptional) 
           { 
            <p>This parameter is <b>optional</b>.</p> 
           } 
           break; 
          default: 
           <p>None.</p> 
           break; 
         } 
        </td> 
       </tr> 
      } 
     } 
    </tbody> 
</table> 

:

나는이에 Parameters.cshtml 템플릿을 업데이트하여 (한 층 아래 만) 파라미터의 형태를 보여 관리가

위와 같이 구현되는 GetFriendlyTypeName() 방법은 여기에 표시된 여기서 How can I get the correct text definition of a generic type using reflection?

그러나, 이것은 나에게 이러한 클래스에서 코멘트를하지 않으며, 중첩 된 유형 도움이되지 않습니다 (예를 들어, 내 모델에 복잡한 형식의 속성이있는 경우 복잡한 형식의 속성을 표시하지 않습니다. 그리고 형식은 XML 주석이 없어도 충분히 유용하지 않습니다.

또한 매개 변수에만 적용되며 HttpResponseMessage 본문에 포함 된 형식을 반환하지 않습니다. Auto generated help pages with return type HttpResponseMessage과 같이 ResponseTypeAttribute을 구현하여 응답 샘플을 얻을 수 있었지만 XML 주석이있는 속성을 다시 제공하지 않습니다. 리플렉션을 사용하여 매개 변수 유형을 다시 얻는 방법과 유사하게 유형을 얻을 수 있지만 실제로 XML 주석을 유형 및 중첩 된 복합 유형을 포함하고 싶습니다.

서비스 호출과 별도로 모델/클래스 문서 (유형 및 XML 주석이있는 속성)를 문서화하고 서비스 호출에 반환하는 유형의 이름 만 표시하도록 허용하는 것이 좋습니다 (적어도 사용자는 해당 유형에 대한 문서를 찾을 수 있습니다).

누구나 매개 변수 또는 반환 형식에 대해 수행하려고하는 것과 비슷한 것을 구현할 수 있습니까? 또는 올바른 방향으로 나를 가리키는 아이디어?

Answer 1

복잡한 유형의 개별 속성을 문서화하는 기능은 현재 개발 중이며 다음 릴리스에서 사용할 수 있습니다. 즉, Nightly 빌드에서 HelpPage 패키지를 얻고 사용해 볼 수 있다고합니다. 이 패키지를 기존 5.0 웹 API 프로젝트로 업그레이드 할 수 있어야합니다.

현재 일반적으로 사용자가 입력 유형 정보에 대해 알고 싶어하는 응답 유형이 아닌 작업의 입력 유형 만 문서화합니다.그러나 사용자가 응답 유형의 정보를 소비하기를 원할 수도 있음을 알 수 있습니다. 우리는이를 조사하여 알려줍니다.

Answer 2

문서 코멘트 Here is a Reference에서 html을 허용하도록 수정할 수 있습니다.

HTML을 허용 한 후에는 XML 문서 param 태그 설명이있는 속성 정보가있는 테이블을 넣을 수 있습니다. 또한 도움말 페이지 HTML 소스를 보면 도움말 페이지 테이블에 사용되는 클래스 속성 이름을 가져올 수 있으므로 테이블은 다른 모든 테이블과 동일한 CSS를 사용합니다.

이것은 해킹이지만 완벽하게 작동합니다.