API文档自动生成，Swagger的配置

ASP.NET的部署方式

第一步：引用程序集

打开NuGet程序包管理器，搜索Swagger，安装第一个，注意画圈的地方，

已经包含主程序和UI了，安装完成后会在根目录App_Start文件夹下生成SwaggerConfig.cs。

第二步：配置信息

打开SwaggerConfig.cs，按照如下配置即可，注意命名空间。

 using System.Web.Http;
 using WebActivatorEx;
 using DemoAPI;
 using Swashbuckle.Application;
 using Swashbuckle.Swagger;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Xml;
 using System.IO;

 [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

 namespace DemoAPI
 {
     public class SwaggerConfig
     {
         public static void Register()
         {
             var thisAssembly = typeof(SwaggerConfig).Assembly;

             GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                {
                    c.SingleApiVersion("v1", "DemoAPI");
                    c.IncludeXmlComments(System.AppDomain.CurrentDomain.BaseDirectory + "/bin/DemoAPI.XML");
                    c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
                })
                .EnableSwaggerUi(c =>
                {
                    //路径规则：项目命名空间.文件夹名称.js文件名称
                    c.InjectJavaScript(thisAssembly, "DemoAPI.Scripts.swagger.js");
                });
         }
     }

     public class CachingSwaggerProvider : ISwaggerProvider
     {
         private static ConcurrentDictionary<string, SwaggerDocument> _cache =
                  new ConcurrentDictionary<string, SwaggerDocument>();

         private readonly ISwaggerProvider _swaggerProvider;

         public CachingSwaggerProvider(ISwaggerProvider swaggerProvider)
         {
             _swaggerProvider = swaggerProvider;
         }

         public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
         {
             var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
             SwaggerDocument srcDoc = null;
             //只读取一次
             if (!_cache.TryGetValue(cacheKey, out srcDoc))
             {
                 srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);

                 srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() } };
                 _cache.TryAdd(cacheKey, srcDoc);
             }
             return srcDoc;
         }

         /// <summary>
         /// 从API文档中读取控制器描述
         /// </summary>
         /// <returns>所有控制器描述</returns>
         public static ConcurrentDictionary<string, string> GetControllerDesc()
         {
             string xmlpath = string.Format("{0}/bin/DemoAPI.XML", System.AppDomain.CurrentDomain.BaseDirectory);
             ConcurrentDictionary<string, string> dic = new ConcurrentDictionary<string, string>();
             if (!File.Exists(xmlpath))
             {
                 return dic;
             }
             XmlDocument doc = new XmlDocument();
             doc.Load(xmlpath);
             XmlNodeList list = doc.SelectNodes("//member[contains(@name,'T:')]");
             foreach (XmlNode item in list)
             {
                 string val = item.Attributes["name"].Value;
                 string key = val.Substring(val.LastIndexOf('.') + ).Replace("Controller", "");
                 XmlNode node = item.FirstChild;
                 if (!dic.ContainsKey(key))
                 {
                     dic.TryAdd(key, node.InnerText.Trim());
                 }
             }
             return dic;
         }

     }
 }

第三步：输出XML文件

右键项目的属性，生成，勾选

第四步：显示控制器备注

第二步中的，EnableSwaggerUi()配置的swagger.js代码如下

$(function () {
    var init = function () {
        $.getJSON($("#input_baseUrl").val(), {}, function (res) {
            $("#resources_container .resource").each(function (i, item) {
                var _id = $(item).attr("id");
                if (!_id) { return; }
                var strSummary = res.ControllerDesc[_id.substring(9)];
                if (strSummary)
                {
                    $(item).children(".heading").children(".options").prepend('<li style="color:#000">' + strSummary + '</li>');
                }
            });
        });
    };
    init();
});

自己加的作用于swagger的资源文件（如js、css等文件），

需要设置，否则会报错；选中文件，右键属性，生成操作改为嵌入的资源。

访问地址为 域名或 ip:port/swagger/ui/index，界面如下：

想要显示action，就要在action上面打上特性标签：

或者修改WebApiConfig.cs中routeTemplate选项的值：

汉化就不需要了，备注是中文就行，也没几个单词。

=============================================================================

ASP.NET Core的部署方式

出自：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

第一步：NuGet中搜索“Swashbuckle.AspNetCore”。

第二步：Startup.cs的配置。

1.引入命名空间“using Swashbuckle.AspNetCore.Swagger;”

2.ConfigureServices方法中加入：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

3.Configure方法中加入：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

生成重启，访问地址为 域名或 ip:port/swagger/index.html