使用Swagger作API接口对接

1、当前项目中存在的问题

　　在前后端分离的项目中，如手机端与接口端对接、WEB项目调用API，进行接口对接的方式一般是先创建WORD文档，然后把各个接口的链接、参数、访问方式、说明等信息粘贴进去。在制作文档的过程中，如果稍有不注意就容易出现文档错误，影响对接接口的准确性。

　　如果接口开发中出现新的需求，导致接口的传入参数、传出参数、链接地址发生改变，则需要同步更新对接文档，并将文件发送给对接的同事。此种对接方式给后端开发的同事增加了较多的工作量，且制作方式非常不灵活，导致对接效率低下

　　后端程序员开发好接口以后，需要自己手动编写测试程序，给开发工作带来了额外的工作量。

2、Swagger解决的问题

　　Swagger是一个自动生成接口文档的工具的，它生成的内容包含接口地址、接口说明、传入参数说明、传入参数示例、传出参数说明、传出参数示例等。它生成文档的依据是代码与备注，如果它生成的文档出错，那么必然是代码写错了，所以根本不用担心文档会出问题。

　　在接口需求变化时，只要把修改后的代码重新生成一下，就可以直接向前端同事展现最新的文档，绝不会出错。与前端同事对接时，只要用口头或通信工具通知对方哪个接口发生了变化即可，不用再手动写文档。
　　同时，Swagger还提供了接口访问功能，在接口生成完成后，可以直接在Swaager界面传入参数进行调试，无需再像之前那样写代码调用接口。

3、Swagger使用方法

3.1、如何引入项目

　　Swagger可用于ASP.NET的MVC、WEBAPI项目，接口生成对象为各个继承ApiController的控制器，控制器里所有的公用方法都会生成对应的文档。配置方案如下：

　　第一步：打开项目，选择工具----Nuget程序包管理器----管理解决方案的Nuget程序包，打开Nuget程序包管理器

　　第二步：在Nuget程序包管理器中选择联机----nuget.org，在右侧的搜索框中输入“Swagger”，然后在搜索结果中点击Swashbuckle行的“安装”按钮。

　　备注：下面的Swagger行也可以使用，但是对于.NET FRAMEWORK版本要求较高，建议在4.5及以上版本中使用

　　第三步：在弹出的安装确认程序中，选择MVC或WEBAPI项目即可，其他项目不要勾选。如果有多个MVC或WEBAPI，可以一起勾选。点击“OK”后安装继续，等待完成即可

3.2 、相关配置

3.2.1、接口路径配置

　　API控制器默认只能访问一个GET接口，我们需要把它配置为可以访问所有接口。打开App_Start\WebApiConfig.cs文件，可以看到routeTemplate的值如下：

api/{controller}/{id}

将它改为“api/{controller}/{action}/{id}”即可

3.2.2、各项目配置

　　我们的传入传出参数如果放在独立的类库中，则应该首先对类库进行下图中的配置。图中配置的意思是如果使用到Entity项目里面的类，则使用SwaggerTest.Entity.XML文件的备注进行生成。

　　需要作此项配置的项目有控制器所在项目、传入传出参数类所在项目，在此DEMO中，参数类放在SwaggerTest.Entity项目中，控制器在SwaggerTest项目中，两个都需要配置。

3.2.3、代码配置

　　打开接口项目的App_Start\SwaggerConfig.cs文件，在EnableSwagger方法中加入以下三行代码：

c.IncludeXmlComments(string.Format("{0}bin\\SwaggerTest.Entity.XML", System.AppDomain.CurrentDomain.BaseDirectory));//启用传入传出参数所在的类库，注意路径与3.2.3的类库文档文件保持一致

c.IncludeXmlComments(string.Format("{0}bin\\SwaggerTest.XML", System.AppDomain.CurrentDomain.BaseDirectory));//启用控制器所在项目，注意路径与3.2.3中的控制器项目文档文件保持一致

c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());//如果一个方法或一个参数有多个备注，则启用第一个。此项如果不配置，有多个备注时会报异常

2、接口开发要求

2.1、传入参数定义

传入参数遵照C#的备注风格，按照下面的写法即可

/// <summary>
/// 请求参数

/// 只能生成一行，此行不会生成到文档里面
/// </summary>
public class ReqeustAEntity
{
/// <summary>
/// 整型参数1
/// </summary>
public int Param1 { get; set; }

/// <summary>
/// 字符串参数2
/// </summary>
public string Param2 { get; set; }
}

2.2、传出参数定义

传出参数同传入参数，使用C#风格的备注，按照下图红框中的写法即可

/// <summary>
/// 方法A返回实体
/// </summary>
public class ResponseAEntity
{
/// <summary>
/// A接口返回参数1
/// </summary>
public string ResAP1 { get; set; }

/// <summary>
/// A接口返回参数2
/// </summary>
public string ResAP2 { get; set; }
}

2.3、接口编写定义

接口备注方法同传入传出参数，在接口上方填写好备注即可。同时在接口上方标注HttpPost或HttGet，可以指定接口请求方法，如果没有标注请求方式，则默认为HttpPost。如果返回信息不是基本类型，注意不要转换为JSON后返回，否则接口文档中无法显示字段备注

/// <summary>
/// 方法A
/// </summary>
/// <param name="request">请求参数</param>
/// <returns></returns>

public ResponseAEntity MethodA(ReqeustAEntity request)
{
ResponseAEntity response = new ResponseAEntity()
{
ResAP1 = "A方法返回参数1",
ResAP2 = "B方法返回参数2"
};
return response;
}

2.4、发布方法

使用VISUAL STUDIO提供的发布方法将接口发布至测试站点以后，应注意将以下文件复制到测试站点的BIN目录下：

SwaggerTest.XML：控制器所在项目生成的XML文件

SwaggerTest.Entity.XML：传入传出参数类所在项目生成的XML文件

备注：如果系统中有多个控制器项目，或有多个传入传出参数项目，需要把这些项目对应的XML文件都复制过去

2.5、文档访问方法

打开接口站点地址，在后面加上/Swagger，即可看到文档。如当前网址为www.baidu.com，则文档地址为www.baidu.com/Swagger。打开地址以后，将自动跳转至文档地址www.baidu.com/swagger/docs/v1

2.6、界面说明