Як Xml Документація для Web 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-документацію для вашого підпроекту (із властивостей проекту / збірки), як у вашому проекті Web API. За винятком цього часу, направляйте його безпосередньо на XmlDocument.xmlтак, щоб він генерувався у кореневій папці вашого проекту.

2. Змініть події після збирання проекту 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;
   }
   

   г. І останнє, виправте всі помилки компілятора (їх повинно бути три), що призводить до посилань на _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 коментує більш ніж 1 файл

тут я надаю посилання на відповідь з ним, яке може вам допомогти. Ви можете легко використовувати кілька XML-файлів для документації.

Сторінка довідки Web Api XML коментує більш ніж 1 файл

Найпростіший спосіб вирішити цю проблему - це створення папки App_Code на розгорнутому сервері. Потім скопіюйте файл XmlDocument.xml у папку bin локально у папку App_Code