Web Api 용 Xml 문서에 기본 프로젝트 이외의 문서를 포함하려면 어떻게해야합니까?

문서 귀하의 웹 API 프로젝트에 해당 xmldoc 통합을 가능하게하여 API 유형의 모든 당신의 WebApi 프로젝트의 일부로 만 핸들 상황에 나타납니다. 특히, App_Data/XmlDocument.xml구성에서 해당 파일을 사용할 줄로 XML 문서를 다시 라우팅 하고 주석 처리를 제거하는 방법에 대해 설명 합니다. 이것은 암시 적으로 하나의 프로젝트 문서 파일 만 허용합니다.

그러나 설정에서 공통 "모델"프로젝트에 정의 된 요청 및 응답 유형이 있습니다. 이는 다음과 같이 정의 된 엔드 포인트가있는 경우를 의미합니다.

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

어디 OpenIdLoginRequest과 같이 별도의 C # 프로젝트에 정의되어 있습니다 :

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

XML 문서 주석에도 불구하고 request엔드 포인트 별 도움말 페이지 (예 :) 를 볼 때 매개 변수 의 속성 에는 문서가 포함되어 있지 않습니다 http://localhost/Help/Api/POST-auth-openid-login.

XML 문서가있는 하위 프로젝트의 유형이 Web API XML 문서에 표시되도록하려면 어떻게해야합니까?

이를 달성하기위한 기본 제공 방법이 없습니다. 그러나 몇 단계 만 필요합니다.

1. Web API 프로젝트와 마찬가지로 하위 프로젝트 (프로젝트 속성 / 빌드에서)에 대한 XML 문서를 활성화합니다. 이번을 제외하고 XmlDocument.xml는 프로젝트의 루트 폴더에 생성되도록 직접 라우팅하십시오 .

2. Web API 프로젝트의 postbuild 이벤트를 수정하여이 XML 파일을 App_Data폴더 에 복사 합니다.

   copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"

   어디에서 Subproject.xml어떤 프로젝트의 이름으로 이름을 변경해야한다 플러스입니다 .xml.

3. 다음으로 열고 Areas\HelpPage\App_Start\HelpPageConfig다음 줄을 찾습니다.

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

   이것은 처음에 XML 도움말 문서를 활성화하기 위해 처음에 주석 처리를 해제 한 줄입니다. 해당 줄을 다음으로 바꿉니다.

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

   이 단계는 XmlDocumentationProvider프로젝트의 특정 XML 파일이 아닌 XML 파일이 포함 된 디렉토리가 전달 되도록합니다 .

4. 마지막으로 Areas\HelpPage\XmlDocumentationProvider다음과 같은 방법 으로 수정 하십시오.

   ㅏ. _documentNavigator필드를 다음으로 바꿉니다 .

   private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();

   비. 생성자를 다음으로 바꿉니다.

   public XmlDocumentationProvider(string appDataPath)
   {
       if (appDataPath == null)
       {
           throw new ArgumentNullException("appDataPath");
       }
   
       var files = new[] { "XmlDocument.xml", "Subproject.xml" };
       foreach (var file in files)
       {
           XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
           _documentNavigators.Add(xpath.CreateNavigator());
       }
   }

   씨. 생성자 아래에 다음 메서드를 추가합니다.

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }

   디. 마지막으로 모든 컴파일러 오류 (3 개가 있어야 함)를 수정 _documentNavigator.SelectSingleNode하여 _documentNavigator.부분 을 참조 하고 제거하여 SelectSingleNode위에서 정의한 새 메서드를 호출합니다 .

이 마지막 단계는 기본 프로젝트가 아닌 여러 XML 문서에서 도움말 텍스트를 찾을 수 있도록 문서 공급자를 수정하는 것입니다.

이제 도움말 문서를 검토 할 때 관련 프로젝트에있는 유형의 XML 문서가 포함됩니다.

나는 이것도 만났지만 나중에 문제를 피하기 위해 생성 된 코드를 편집하거나 복제하고 싶지 않았습니다.

다른 답변을 기반으로 여러 XML 소스에 대한 자체 포함 문서 공급자가 있습니다. 프로젝트에 이것을 드롭하십시오.

/// <summary>A custom <see cref="IDocumentationProvider"/> that reads the API documentation from a collection of XML documentation files.</summary>
public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
    /*********
    ** Properties
    *********/
    /// <summary>The internal documentation providers for specific files.</summary>
    private readonly XmlDocumentationProvider[] Providers;


    /*********
    ** Public methods
    *********/
    /// <summary>Construct an instance.</summary>
    /// <param name="paths">The physical paths to the XML documents.</param>
    public MultiXmlDocumentationProvider(params string[] paths)
    {
        this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(MemberInfo subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(Type subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpControllerDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpParameterDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetResponseDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetResponseDocumentation(subject));
    }


    /*********
    ** Private methods
    *********/
    /// <summary>Get the first valid result from the collection of XML documentation providers.</summary>
    /// <param name="expr">The method to invoke.</param>
    private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)
    {
        return this.Providers
            .Select(expr)
            .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
    }
}

... HelpPageConfig원하는 XML 문서에 대한 경로를 사용하여 활성화하십시오 .

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Api.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.Models.xml")));

이를 수행하는 한 가지 더 간단한 방법은 xml 파일을 병합하는 것입니다. 아래 답장의 예제 코드 :

둘 이상의 파일에서 Web Api 도움말 페이지 XML 주석

여기에 도움이 될 수있는 답변 링크를 제공합니다. 문서화를 위해 여러 XML 파일을 쉽게 사용할 수 있습니다.

둘 이상의 파일에서 Web Api 도움말 페이지 XML 주석

이 문제를 해결하는 가장 쉬운 방법은 배포 한 서버에 App_Code 폴더를 만드는 것입니다. 그런 다음 bin 폴더에있는 XmlDocument.xml을 로컬로 App_Code 폴더에 복사합니다.