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}\bin\{1}.XML",System.AppDomain.CurrentDomain.BaseDirectory,name);
             return xmlName;
         }
     }
 }

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

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

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