IT轮子系列（二）——mvc API 说明文档的自动生成——Swagger的使用（一）

这篇文章主要介绍如何使用Swashbuckle插件在VS 2013中自动生成MVC API项目的说明文档。为了更好说明的swagger生成，我们从新建一个空API项目开始。

第一步、新建mvc api 项目

---

右键解决方案—>添加/新建项目，如下图：

然后，选择API项目模版，下图所示：

至此，我们的空项目已经创建完成。

第二步、添加插件Swashbuckle的引用

---

在添加引用包前，我们先看看空api项目一些基本组成，主要关注APP_Start文件夹的内容，下图所示：

‘’

我们可以清楚的看到，在APP_Start文件下新建的API项目只有四个文件。

接下来，我们引用Swashbuckle插件。

右键项目/管理NeGut 程序包，打开程序包管理界面，选择 联机搜索Swashbuckle 插件。如下图：

 然后，点击 安装。

当安装完成的时候，我们会发现在APP_Start 文件下多出了一个文件SwaggerConfig.cs 。下图所示：

至此，Swashbuckle 插件已经成功引入到我们的项目当中。

第三步、Swashbuckle 插件的实战使用

---

在HomeController 中，添加如下跳转语句：

点击F5,运行项目，我们就在浏览器中看到如下界面：

至此说明，Swashbuckle 插件的配置已完成。

第四步、如何添加接口、数据模型的说明

---

首先，右键项目/属性->生成，勾选XML文档文件->保存，如下图：

其次，配置SwaggerConfig.cs 文件，如下代码所示：

在自动生成的这个配置文件中，还有很多英文说明，为了页面更简洁，已删掉。大家在在实际项目中，可按说明配置。

using System.Web.Http;
using WebActivatorEx;
using ITWheels.Swagger;
using Swashbuckle.Application;

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

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

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {                        
                        c.SingleApiVersion("v1", "ITWheels.Swagger");

                        /*包含注释说明                                               
                         * 如果要包含多个xml文件，可参照GetXmlCommentsPath 方法。
                         * 写多个c.IncludeXmlComments
                        */
                        c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
                        
                    })
                .EnableSwaggerUi(c =>
                    {
                        
                    });
        }

        private static string GetXmlCommentsPath(string name)
        {
            //获取项目dll 所在的bin目录
            string xmlName = string.Format(@"{0}in{1}.XML",System.AppDomain.CurrentDomain.BaseDirectory,name);
            return xmlName;
        }
    }
}

最后，在我们的接口中添加注释。

点击F5，运行项目，我们将会看到如下界面，注释说明已经出现在文档中，如下图：

至此，Swashbuckle 插件基本使用已经大功告成拉，下篇，将给大家介绍下，稍进一步的应用。晚安 2017-10-21 22:39:37