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

Question

У меня есть разные плагины в моем проекте Web API с их собственными документами XML, и у меня есть одна централизованная страница справки, но проблема в том, что страница справки Web Api по умолчанию поддерживает только один файл документации

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

Как можно загрузить конфиг из разных файлов? Я хочу сделать что-то вроде этого:

new XmlDocumentationProvider("PluginsFolder/*.xml")

Answer 1

Вы можете изменить установленное XmlDocumentationProvider в Areas\HelpPage сделать что-то вроде следующего:

Объедините несколько файлов документов Xml в один:

Пример кода (отсутствуют некоторые проверки и проверки ошибок):

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();

Answer 2

Решение Киранс работает очень хорошо. В итоге я использовал его подход, но создал копию XmlDocumentationProvider с именем MultiXmlDocumentationProvider с измененным конструктором:

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

Я регистрирую нового провайдера из HelpPageConfig.cs:

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

Создание нового класса и оставление исходного без изменений может быть более удобным при обновлении и т. Д.

Answer 3

Вместо того, чтобы создавать отдельный класс по образцу XmlMultiDocumentationProvider, я просто добавил конструктор в существующий XmlDocumentationProvider. Вместо того, чтобы брать имя папки, он берет список строк, так что вы все равно можете точно указать, какие файлы вы хотите включить (если в каталоге, в котором находится XML-документация, есть другие файлы XML, это может стать проблематичным). Вот мой новый конструктор:

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

HelpPageConfig.cs выглядит следующим образом. (Да, может быть меньше строк, но у меня нет ограничения на количество строк, поэтому мне нравится разбивать его на части.)

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 4

Я согласен с gurra777, что создание нового класса - более безопасный путь обновления. Я начал с этого решения, но оно включает в себя достаточное количество копий / пасты, которые могут легко устареть после нескольких обновлений пакетов.

Вместо этого я держу коллекцию XmlDocumentationProvider дети. Для каждого из методов реализации я призываю детей получить первый непустой результат.

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...

Регистрация в HelpPageConfig такая же, как в ответе gurra777,

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