通达信交易接口-使用Swagger作API接口对接_wxl847466025的博客

当前项目中存在的问题

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

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

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

Swagger解决的问题

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

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

Swagger使用方法

如何引入项目

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

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

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

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

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

相关配置

通达信交易接口,接口路径配置

API控制器默认只能访问一个GET通达信交易接口,接口，我们需要把它配置为可以访问所有通达信交易接口,接口。打开App_StartWebApiConfics文件，可以看到routeTemplate的值如下：

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

各项目配置

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

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

代码配置

打开通达信交易接口,接口项目的App_StartSwaggerConfics文件，在EnableSwagger方法中加入以下三行代码：

IncludeXmlComments(strinFormat('{0}binSwaggerTest.Entity.XML',SysteAppDomaiCurrentDomaiBaseDirectory));//启用传入传出参数所在的类库，注意路径与3的类库文档文件保持一致

IncludeXmlComments(strinFormat('{0}binSwaggerTest.XML',SysteAppDomaiCurrentDomaiBaseDirectory));//启用控制器所在项目，注意路径与3中的控制器项目文档文件保持一致

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

通达信交易接口,接口开发要求

传入参数定义

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

///

///请求参数

///只能生成一行，此行不会生成到文档里面///

publicclassReqeustAEntity{///

///整型参数1///

publicintParam1{get;set;}

///

///字符串参数2///

publicstringParam2{get;set;}}

传出参数定义

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

///

///方法A返回实体///

publicclassResponseAEntity{///

///A通达信交易接口,接口返回参数1///

publicstringResAP1{get;set;}

///

///A通达信交易接口,接口返回参数2///

publicstringResAP2{get;set;}}

通达信交易接口,接口编写定义

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

///

///方法A///

///请求参数///

publicResponseAEntityMethodA(ReqeustAEntityrequest){ResponseAEntityresponse=newResponseAEntity(){ResAP1='A方法返回参数1',ResAP2='B方法返回参数2'};returnresponse;}

发布方法

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

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

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

文档访问方法

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

界面说明