問(wèn)題描述

在webapi項(xiàng)目中使用swagger作為接口文檔是個(gè)很好的選擇，但是有時(shí)候會(huì)遇到一些小問(wèn)題。在單項(xiàng)目中大家都知道swagger會(huì)解析項(xiàng)目生成的xml注釋文件，將注釋添加到接口信息。但是如果分成多個(gè)項(xiàng)目會(huì)遇到注釋只會(huì)在webapi項(xiàng)目中有解析，依賴(lài)的項(xiàng)目中的注釋無(wú)法解析的情況。

問(wèn)題原因

在配置swagger過(guò)程中，為了加入注釋?zhuān)枰腠?xiàng)目生成的xml注釋文檔。但是一個(gè)項(xiàng)目的注釋文檔只會(huì)生成自身的注釋文檔。他依賴(lài)的項(xiàng)目注釋并不會(huì)放入。于是乎swagger就認(rèn)為你引用的Model沒(méi)有注釋。當(dāng)然不會(huì)有描述了。

解決方案

其實(shí)很簡(jiǎn)單的思路。在項(xiàng)目啟動(dòng)文件里，執(zhí)行文檔合并的代碼。將依賴(lài)的項(xiàng)目文檔合并到主項(xiàng)目的文檔中去。

具體實(shí)現(xiàn)

在各個(gè)需要生成注釋文檔的csproj文件里加入如下節(jié)點(diǎn)

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

合并文檔代碼

            var directory = AppDomain.CurrentDomain.BaseDirectory;
            // 找到所有的注釋文檔， 根據(jù)你的項(xiàng)目情況加上通配符。
            var files = Directory.GetFiles(directory, "XXX.xml").ToList();
           // 找到你的主項(xiàng)目注釋文檔
            var mainFile = files.Where(u => u.Contains("XXXMain.xml")).FirstOrDefault();
            if (string.IsNullOrEmpty(mainFile))
                return;
            files.Remove(mainFile);
            if (files.Count == 0)
                return;
            var mainDoc = new XmlDocument();
            mainDoc.Load(mainFile);
            var membersNode = mainDoc.SelectSingleNode("http://members");
            files.ForEach(file => {
                var doc = new XmlDocument();
                doc.Load(file);
                var nodes = doc.SelectNodes("http://member");
                foreach(XmlNode node in nodes)
                {
                    var importNode = mainDoc.ImportNode(node, true);
                    membersNode.AppendChild(importNode);
                }
            });
            files.ForEach(u =>
            {
                File.Delete(u);
            });
            mainDoc.Save(mainFile);

缺陷

會(huì)導(dǎo)致應(yīng)用啟動(dòng)會(huì)慢一點(diǎn)。