Как Xml Documentation для Web Api включает документацию из-за основного проекта?

Документация для включения интеграции XmlDoc в ваши проекты Web Api, по-видимому, относится только к ситуациям, когда все ваши типы API являются частью вашего проекта WebApi. В частности, в нем обсуждается, как перенаправить XML-документацию в App_Data/XmlDocument.xml и раскомментировать строку в вашем конфиге, которая будет потреблять этот файл. Это подразумевает только файл документации для одного проекта.

Однако в моей настройке у меня есть свои типы запросов и ответов, определенные в общем проекте «Модели». Это означает, что если у меня есть конечная точка, такая как:

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

Где OpenIdLoginRequest определен в отдельном проекте C # так:

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

Несмотря на документы XML doccomments, свойства параметра request не содержат документации при просмотре страницы справки по конкретным точкам (например, http://localhost/Help/Api/POST-auth-openid-login ).

Как я могу сделать так, чтобы типы в подпроектах с документацией XML всплывали в документации по API Web API?

    Для этого нет встроенного способа. Однако для этого требуется всего несколько шагов:

    1. Включите XML-документацию для вашего подпроекта (из свойств / сборки проекта), как и для вашего проекта веб-API. За исключением этого времени, направьте его прямо в XmlDocument.xml чтобы он был сгенерирован в корневой папке вашего проекта.

    2. Измените событие postbuild для проекта Web API, чтобы скопировать этот XML-файл в папку App_Data :

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

      Где Subproject.xml следует переименовать в любое имя вашего проекта плюс .xml .

    3. Затем откройте Areas\HelpPage\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 _documentNavigators = new List(); 

      б. Замените конструктор на:

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

      с. Добавьте следующий конструктор ниже конструктора:

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

      д. И последнее, исправить все compiler errors (должно быть три), что приведет к ссылкам на _documentNavigator.SelectSingleNode и удалит _documentNavigator. так что теперь он вызывает новый метод SelectSingleNode который мы определили выше.

    Этот последний шаг – это то, что изменяет поставщика документов для поддержки поиска в нескольких XML-документах для текста справки, а не только для основного проекта.

    Теперь, когда вы изучите свою справочную документацию, она будет содержать документацию XML от типов в вашем связанном проекте.

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

    Основываясь на других ответах, здесь есть автономный поставщик документации для нескольких источников XML. Просто добавьте это в свой проект:

     /// A custom  that reads the API documentation from a collection of XML documentation files. public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider { /********* ** Properties *********/ /// The internal documentation providers for specific files. private readonly XmlDocumentationProvider[] Providers; /********* ** Public methods *********/ /// Construct an instance. /// The physical paths to the XML documents. public MultiXmlDocumentationProvider(params string[] paths) { this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray(); } /// Gets the documentation for a subject. /// The subject to document. public string GetDocumentation(MemberInfo subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } /// Gets the documentation for a subject. /// The subject to document. public string GetDocumentation(Type subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } /// Gets the documentation for a subject. /// The subject to document. public string GetDocumentation(HttpControllerDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } /// Gets the documentation for a subject. /// The subject to document. public string GetDocumentation(HttpActionDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } /// Gets the documentation for a subject. /// The subject to document. public string GetDocumentation(HttpParameterDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } /// Gets the documentation for a subject. /// The subject to document. public string GetResponseDocumentation(HttpActionDescriptor subject) { return this.GetFirstMatch(p => p.GetResponseDocumentation(subject)); } /********* ** Private methods *********/ /// Get the first valid result from the collection of XML documentation providers. /// The method to invoke. private string GetFirstMatch(Func 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

    Давайте будем гением компьютера.