WebApi使用swagger ui自动生成接口文书档案

以前LZ也是多少个通篇注释的Coder,可是自从到那一个集团,除了写别人调用的api,有个大致的api功效描述,其余什么都还没。OK,笔者就不但说不练了,给大家看看作者的代码先。

在此之前就写到。前段时间正值使用webapi。这里介绍三个实用的事物swageer ui
前段时间开支都以左右端分开。我们这里是给前端提供api。一时候对于一个api的描述,并不想特别写生龙活虎份文书档案。很浪费时间。
swagger ui就是一个能整合到项目中让api的批注能够生成到一个网页上。能简单测验和给前端看。
开怼吧。

usingSystem;usingSystem.Collections.Generic;usingSystem.Text;usingSystem.Collections;usingSystem.Collections.Specialized;usingSystem.Web;usingSystem.IO;usingXXX.Lib;namespaceXXX{//Url辅助类:对Url进行初步的解析publicclassUrlHelper{constintMAX_URI_LENGTH=512;string_scriptName=string.Empty;CommandResult_parseResult=CommandResult.Success;NameValueCollection_parameters=newNameValueCollection();char[]_uriInvalidChar=newchar[]{'/','\\'};char[]_pathInvalidChar=newchar[]{'/','\\',':','*','?','\"','','','|'};publicUri_uri=null;publicstringScriptName{get{return_scriptName;}}publicNameValueCollectionParameters{get{return_parameters;}}publicCommandResultParseResult{get{return_parseResult;}}publicUrlHelper(UrioriginalUri){_uri=ReplaceUri(originalUri);if(IsUriLengthError()){return;}if(CheckPathAndQuery()){ParsePathAndQuery();}}privateUriReplaceUri(UrioriginalUri){stringuriStr=ReplaceUriWithUrlModel(originalUri);if(uriStr==""){returnoriginalUri;}else{returnnewUri(uriStr);}}privatestaticstringReplaceUriWithUrlModel(UrioriginalUri){string[]splitStr=null;try{foreach(variteminFile.ReadAllLines(Hisan.Lib.SystemLib.GetAppRootDir()+"UrlModel.ini")){splitStr=item.Split(newstring[]{"-"},StringSplitOptions.RemoveEmptyEntries);if(splitStr==null||splitStr.Length!=2){continue;}if(splitStr[0].Trim()==originalUri.PathAndQuery.Substring(1)){returnoriginalUri.AbsoluteUri.Replace(splitStr[0].Trim(),splitStr[1].Trim());}}}catch{}return"";}privateboolIsUriLengthError(){if(_uri==null||_uri.ToString().LengthMAX_URI_LENGTH){_parseResult=CommandResult.UrlTooLong;returntrue;}returnfalse;}privateboolCheckPathAndQuery(){stringpathAndQuery=_uri.PathAndQuery.Substring(1);if(IsUrlInvalidChar(pathAndQuery)){returnfalse;}if(pathAndQuery.IndexOfAny(_uriInvalidChar)=0){_parseResult=CommandResult.UrlInvalidChar;returnfalse;}elseif(pathAndQuery.Length==0){_parseResult=CommandResult.NoExistsMethod;returnfalse;}string[]splitPathAndQuery=newstring[]{};if(IsFileNameInvalidChar(pathAndQuery,splitPathAndQuery)){returnfalse;}returntrue;}privateboolIsFileNameInvalidChar(stringpathAndQuery,string[]splitPathAndQuery){splitPathAndQuery=pathAndQuery.Split(newchar[]{'?'},StringSplitOptions.RemoveEmptyEntries);if(splitPathAndQuery[0].IndexOfAny(_pathInvalidChar)=0){_parseResult=CommandResult.FileNameInvalidChar;returntrue;}returnfalse;}privateboolIsUrlInvalidChar(stringpathAndQuery){if(pathAndQuery.IndexOfAny(_uriInvalidChar)=0){_parseResult=CommandResult.UrlInvalidChar;returntrue;}returnfalse;}privatevoidParsePathAndQuery(){string[]splitPathAndQuery=_uri.PathAndQuery.Substring(1).Split(newchar[]{'?'},StringSplitOptions.RemoveEmptyEntries);SetScriptNameAndParameters(splitPathAndQuery);}privatevoidSetScriptNameAndParameters(string[]splitPathAndQuery){_scriptName=splitPathAndQuery[0];if(splitPathAndQuery.Length1){_parameters=HttpUtility.ParseQueryString(splitPathAndQuery[1],Encoding.UTF8);}}}}

Step.1 Nuget安装
开荒你的Nuget console,Install-Package Swashbuckle(要选择哪个项目)
图片 1

有人会问,为何写成这么多小方法,其实这么些是根源一本书CleanCode,而不写注释的主见也是来源于那本书。文章中央思想是为着以写遗闻的方法来写程序。拿出一小段为例,我给加上中文注释看看效果怎么样。

ps.其实第一步安装完了,你怎么着绝不做。运营起来,网站步向/swagger/ui/index就能够看到你的那个api了(不带注释),然则没到达我们的预料效能——将注释自动生成到文书档案上。so,继续往下看

publicUrlHelper(UrioriginalUri){//替换Uri,如果跟进这个方法看的话,会发现把原来的请求更换成已经内置好的Url,这个是为了兼容旧版本Url的,当然这个本不应该存在,但当时那个版本没有自动升级,所以这个没办法。权且当成合适的好了,而且这也不是本次讨论的重点。_uri=ReplaceUri(originalUri);//如果Uri的长度错误if(IsUriLengthError()){//返回return;}//如果检查路径和查询成功另外一个原因是维护的时候,或者修改Bug的时候大多数人都会忘了去修改注释,导致注释和程序不匹配。这样后来的人看注释和程序不匹配,他就会想到底哪个错了。就算他不想,只认为程序是对的,OK。那他还要想改不改错误的注释呢?虽然这个是不应该出现的问题,但这种问题却常常出现。当然这种方法利弊都有,下面说下弊端。1.对开发工具要求较高,当然VS还是很给力的,F12就可以跟着方法名进入方法。但一些没有此功能的开发工具来说,去那么多代码中来找对应的方法,还是很头疼的。2.较大的项目不太适合,比如一些开源的。那么多类,还全是英文,没有注释,找起来着实头疼。另外一般那样的项目修改的人很多,出现几个不受规矩的程序员就着实让人头疼,他看着别人不写注释自己也不写,但是逻辑组织的又不是很好。本文仅作抛砖引玉之用,看看大家对无注释编程有何看法,以及普遍程度如何。但就目前来看,大多数人看到没有注释的程序都会大喊“垃圾”。尤其篇幅较长的。但有些篇幅较长的确实是因为其特殊性没有办法进行小方法拆分,比如一些特殊的算法,拆开了反而逻辑不好。

 

Step.2 加上生成注释的代码
安装之后会在App_Start文件夹中多了SwaggerConfig.cs类,该类中的Register(卡塔尔方法会在应用程序运维的时候调用
个中超级多注脚,绿绿的,照旧选取原谅她,删掉呢,删掉后就那剩余那么些

 1 public static void Register()
 2 {
 3   var thisAssembly = typeof(SwaggerConfig).Assembly;
 4 
 5   GlobalConfiguration.Configuration
 6   .EnableSwagger(c =>
 7   {
 8     c.SingleApiVersion("v1", "WebApplication1");
 9   })
10   .EnableSwaggerUi(c =>
11   {
12 
13   });
14 }

稍加改动一下,附加个注释xml上去

 1 public static void Register()
 2 {
 3     var thisAssembly = typeof(SwaggerConfig).Assembly;
 4 
 5     GlobalConfiguration.Configuration
 6     .EnableSwagger(c =>
 7     {
 8         c.SingleApiVersion("v1", "WebApplication1");
 9         c.IncludeXmlComments(GetXmlCommentsPath());
10     })
11     .EnableSwaggerUi(c =>
12     {    
13 
14     });
15 }
16 private static string GetXmlCommentsPath()
17 {
18     return System.String.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory);
19 }

 

Step.3 步骤2所务必的
启用生成xml文书档案,右击项目文件属性 bulid公布——Output输出(勾选XML文件)
图片 2