Как может документация Xml для веб-API включать документацию, выходящую за рамки основного проекта?

Документация для обеспечения интеграции XmlDoc в ваши Api проектов Web появляется только рукоятки ситуаций , когда все ваши типов API являются частью вашего WebAPI проекта. В частности, обсуждается, как перенаправить XML-документацию App_Data/XmlDocument.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-документацией отображались в XML-документации Web API?

Для этого нет встроенного способа. Однако для этого требуется всего несколько шагов:

1. Включите XML-документацию для своего подпроекта (из свойств / сборки проекта), как для проекта веб-API. За исключением этого раза, направьте его напрямую, чтобы XmlDocument.xmlон был создан в корневой папке вашего проекта.

2. Измените событие postbuild вашего проекта Web API, чтобы скопировать этот 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());
       }
   }

   c. Добавьте следующий метод под конструктором:

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

   d. И, наконец, исправьте все ошибки компилятора (их должно быть три), приводящие к ссылкам _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. Пример кода в моем ответе ниже:

XML-комментарии на странице справки веб-API из более чем 1 файла

Самый простой способ решить эту проблему - создать папку App_Code на развернутом сервере. Затем скопируйте XmlDocument.xml, который находится в папке bin, локально в папку App_Code.