Comment la documentation Xml pour Web Api peut-elle inclure de la documentation au-delà du projet principal?

La documentation permettant d'activer l'intégration de XmlDoc dans vos projets Web Api semble gérer uniquement les situations où tous vos types d'API font partie de votre projet WebApi. En particulier, il explique comment rediriger la documentation XML vers App_Data/XmlDocument.xmlet décommenter une ligne de votre configuration qui consommera ce fichier. Cela autorise implicitement uniquement le fichier de documentation d'un projet.

Cependant, dans ma configuration, j'ai mes types de demande et de réponse définis dans un projet "Modèles" commun. Cela signifie que si j'ai un point de terminaison défini tel que:

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

Où OpenIdLoginRequestest défini dans un projet C # séparé comme ceci:

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

    ...
}

Malgré les problèmes XML, les propriétés du requestparamètre ne contiennent aucune documentation lorsque vous affichez la page d'aide spécifique au point final (c'est-à-dire http://localhost/Help/Api/POST-auth-openid-login).

Comment puis-je faire en sorte que les types de sous-projets avec la documentation XML apparaissent dans la documentation XML de l'API Web?

Il n'y a pas de moyen intégré pour y parvenir. Cependant, cela ne nécessite que quelques étapes:

1. Activez la documentation XML pour votre sous-projet (à partir des propriétés / build du projet) comme vous l'avez fait pour votre projet API Web. Sauf cette fois, acheminez-le directement vers XmlDocument.xmlafin qu'il soit généré dans le dossier racine de votre projet.

2. Modifiez l'événement de post-construction de votre projet API Web pour copier ce fichier XML dans votre App_Datadossier:

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

   Où Subproject.xmldevrait être renommé quel que soit le nom de votre projet plus .xml.

3. Ensuite, ouvrez Areas\HelpPage\App_Start\HelpPageConfiget localisez la ligne suivante:

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

   Il s'agit de la ligne que vous avez initialement décommentée afin d'activer la documentation d'aide XML en premier lieu. Remplacez cette ligne par:

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

   Cette étape garantit que XmlDocumentationProviderle répertoire contenant vos fichiers XML est transmis plutôt que le fichier XML spécifique à votre projet.

4. Enfin, modifiez Areas\HelpPage\XmlDocumentationProviderde la manière suivante:

   une. Remplacez le _documentNavigatorchamp par:

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

   b. Remplacez le constructeur par:

   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. Ajoutez la méthode suivante sous le constructeur:

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

   ré. Enfin, corrigez toutes les erreurs du compilateur (il devrait y en avoir trois) entraînant des références _documentNavigator.SelectSingleNodeet supprimez la _documentNavigator.partie afin qu'elle appelle maintenant la nouvelle SelectSingleNodeméthode que nous avons définie ci-dessus.

Cette dernière étape est ce qui modifie le fournisseur de documents pour prendre en charge la recherche dans plusieurs documents XML du texte d'aide plutôt que du seul projet principal.

Maintenant, lorsque vous examinez votre documentation d'aide, elle inclura la documentation XML des types de votre projet associé.

J'ai rencontré cela aussi, mais je ne voulais pas modifier ou dupliquer le code généré pour éviter des problèmes plus tard.

En s'appuyant sur les autres réponses, voici un fournisseur de documentation autonome pour plusieurs sources XML. Déposez simplement ceci dans votre projet:

/// <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));
    }
}

... et activez-le dans votre HelpPageConfigavec les chemins d'accès aux documents XML souhaités:

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

Une autre façon simplifiée de procéder consiste à fusionner les fichiers xml. Exemple de code dans ma réponse ci-dessous:

Commentaires XML de la page d'aide Web Api provenant de plusieurs fichiers

ici, je fournis un lien de réponse avec elle, qui peut vous aider. Vous pouvez facilement utiliser plusieurs fichiers XML pour la documentation.

Commentaires XML de la page d'aide Web Api provenant de plusieurs fichiers

Le moyen le plus simple de résoudre ce problème consiste à créer le dossier App_Code sur le serveur que vous avez déployé. Copiez ensuite le XmlDocument.xml que vous avez dans votre dossier bin localement dans le dossier App_Code