asp.net - valid - visual studio generate documentation from comments

Página de ayuda de Web Api comentarios XML de más de 1 archivos

Question

Tengo diferentes complementos en mi proyecto Web api con sus propios documentos XML, y tengo una página de Ayuda centralizada, pero el problema es que la página de Ayuda predeterminada de la Web Api solo admite archivos de documentación individuales

new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Documentation.xml"))

¿Cómo es posible cargar config desde diferentes archivos? Quiero hacer algo como esto:

new XmlDocumentationProvider("PluginsFolder/*.xml")

Answer 1

En lugar de crear una clase separada a lo largo de las líneas de XmlMultiDocumentationProvider, acabo de agregar un constructor al XmlDocumentationProvider existente. En lugar de tomar un nombre de carpeta, toma una lista de cadenas para que pueda especificar exactamente qué archivos desea incluir (si hay otros archivos xml en el directorio en el que se encuentra el XML de documentación, es posible que sea ​​difícil). Aquí está mi nuevo constructor:

public XmlDocumentationProvider(IEnumerable<string> documentPaths)
{
if (documentPaths.IsNullOrEmpty())
{
throw new ArgumentNullException(nameof(documentPaths));
}
XDocument fullDocument = null;
foreach (var documentPath in documentPaths)
{
if (documentPath == null)
{
throw new ArgumentNullException(nameof(documentPath));
}
if (fullDocument == null)
{
using (var stream = File.OpenRead(documentPath))
{
fullDocument = XDocument.Load(stream);
}
}
else
{
using (var stream = File.OpenRead(documentPath))
{
var additionalDocument = XDocument.Load(stream);
fullDocument?.Root?.XPathSelectElement("/doc/members").Add(additionalDocument?.Root?.XPathSelectElement("/doc/members").Elements());
}
}
}
_documentNavigator = fullDocument?.CreateNavigator();
}

El HelpPageConfig.cs se ve así. (Sí, puede haber menos líneas, pero no tengo un límite de líneas, así que me gusta dividirlo).

var xmlPaths = new[]
{
HttpContext.Current.Server.MapPath("~/bin/Path.To.FirstNamespace.XML"),
HttpContext.Current.Server.MapPath("~/bin/Path.To.OtherNamespace.XML")
};
var documentationProvider = new XmlDocumentationProvider(xmlPaths);
config.SetDocumentationProvider(documentationProvider);

Answer 2

Estoy de acuerdo con gurra777 en que crear una nueva clase es una ruta de actualización más segura. Comencé con esa solución, pero implica una buena cantidad de copias / pastas, que podrían desactualizarse fácilmente después de algunas actualizaciones de paquetes.

En cambio, estoy guardando una colección de hijos XmlDocumentationProvider . Para cada uno de los métodos de implementación, estoy llamando a los niños para obtener el primer resultado no vacío.

public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
private IList<XmlDocumentationProvider> _documentationProviders;
public MultiXmlDocumentationProvider(string xmlDocFilesPath)
{
_documentationProviders = new List<XmlDocumentationProvider>();
foreach (string file in Directory.GetFiles(xmlDocFilesPath, "*.xml"))
{
_documentationProviders.Add(new XmlDocumentationProvider(file));
}
}
public string GetDocumentation(System.Reflection.MemberInfo member)
{
return _documentationProviders
.Select(x => x.GetDocumentation(member))
.FirstOrDefault(x => !string.IsNullOrWhiteSpace(x));
}
//and so on...

El registro de HelpPageConfig es el mismo que en la respuesta de gurra777,

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

Answer 3

La solución de Kirans funciona muy bien. Terminé usando su enfoque pero creando una copia de XmlDocumentationProvider , llamada MultiXmlDocumentationProvider , con un constructor alterado:

public MultiXmlDocumentationProvider(string xmlDocFilesPath)
{
XDocument finalDoc = null;
foreach (string file in Directory.GetFiles(xmlDocFilesPath, "*.xml"))
{
using (var fileStream = File.OpenRead(file))
{
if (finalDoc == null)
{
finalDoc = XDocument.Load(fileStream);
}
else
{
XDocument xdocAdditional = XDocument.Load(fileStream);
finalDoc.Root.XPathSelectElement("/doc/members")
.Add(xdocAdditional.Root.XPathSelectElement("/doc/members").Elements());
}
}
}
// Supply the navigator that rest of the XmlDocumentationProvider code looks for
_documentNavigator = finalDoc.CreateNavigator();
}

Registro el nuevo proveedor de HelpPageConfig.cs :

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

Crear una nueva clase y dejar la original sin cambios puede ser más conveniente al actualizar, etc.

Answer 4

Puede modificar el XmlDocumentationProvider instalado en Areas/HelpPage para hacer algo como lo siguiente:

Combine varios archivos de documentos XML en uno solo:

Código de ejemplo (faltan algunas verificaciones de errores y validación):

using System.Xml.Linq;
using System.Xml.XPath;
XDocument finalDoc = null;
foreach (string file in Directory.GetFiles(@"PluginsFolder", "*.xml"))
{
if(finalDoc == null)
{
finalDoc = XDocument.Load(File.OpenRead(file));
}
else
{
XDocument xdocAdditional = XDocument.Load(File.OpenRead(file));
finalDoc.Root.XPathSelectElement("/doc/members")
.Add(xdocAdditional.Root.XPathSelectElement("/doc/members").Elements());
}
}
// Supply the navigator that rest of the XmlDocumentationProvider code looks for
_documentNavigator = finalDoc.CreateNavigator();