web-dev-qa-db-fra.com

Comment la documentation XML pour Web Api peut-elle inclure une documentation dépassant le projet principal?

La documentation permettant d'activer l'intégration de XmlDoc dans vos projets Web Api semble ne gérer que les situations dans lesquelles tous vos types d'API font partie de votre projet WebApi. En particulier, il explique comment rediriger la documentation XML vers App_Data/XmlDocument.xml et décommenter une ligne dans votre config qui consommera ce fichier. Cela ne permet implicitement que la documentation d'un projet.

Cependant, dans ma configuration, mes types de demande et de réponse sont 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ù OpenIdLoginRequest est 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 doccomments XML, les propriétés du paramètre request ne contiennent aucune documentation lorsque vous affichez la page d’aide spécifique au noeud final (c.-à-d. http://localhost/Help/Api/POST-auth-openid-login).

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

c#asp.net-web-apixml-documentation
100
Kirk Woll

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

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

  2. Modifiez l'événement postbuild de votre projet API Web pour copier ce fichier XML dans votre dossier App_Data:

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

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

  3. Ouvrez ensuite Areas\HelpPage\HelpPageConfig Et localisez la ligne suivante:

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

    C'est 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 XmlDocumentationProvider se voit attribuer le répertoire contenant vos fichiers XML, plutôt que le fichier XML spécifique de votre projet.

  4. Enfin, modifiez Areas\HelpPage\XmlDocumentationProvider Comme suit:

    une. Remplacez le champ _documentNavigator Par:

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

    b. Remplace 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é. Et enfin, corrigez toutes les erreurs du compilateur (il devrait y en avoir trois) entraînant des références à _documentNavigator.SelectSingleNode Et supprimez la partie _documentNavigator. Pour qu'elle appelle maintenant la nouvelle méthode SelectSingleNode que nous avons définie ci-dessus. .

Cette dernière étape modifie le fournisseur de document pour permettre la recherche dans plusieurs documents XML du texte d'aide plutôt que seulement du projet principal.

Désormais, lorsque vous examinerez votre documentation d'aide, celle-ci inclura une documentation XML provenant de types de votre projet associé.

160
Kirk Woll

J'ai aussi rencontré ce problème, mais je ne voulais pas éditer ni dupliquer le code généré pour éviter des problèmes plus tard.

En vous appuyant sur les autres réponses, voici un fournisseur de documentation autonome pour plusieurs sources XML. Il suffit de déposer 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 HelpPageConfig avec 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")));
30
Pathoschild

Une autre méthode simplifiée consiste à fusionner les fichiers XML. Exemple de code dans ma réponse ci-dessous:

Commentaires XML de la page d'aide de Web Api de plus de 1 fichiers

5
Kiran Challa

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 fichier XmlDocument.xml que vous avez localement dans votre dossier bin dans le dossier App_Code.

0
Ziregbe Otee

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

Commentaires XML de la page d'aide de Web Api de plus de 1 fichiers

0
Shekhar Patel