webapi文档描述-swagger
2021-03-19 08:23
标签:响应 dep 内容 疑问 reflect 说明 inf 警告 ide 转自:https://www.cnblogs.com/yanweidie/p/5709113.html 最近做的项目使用mvc+webapi,采取前后端分离的方式,后台提供API接口给前端开发人员。这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用word文档方式进行交流,实际操作中却很少动手去写。为了解决这个问题,特意在博客园中搜索了一下api接口文档生成的文章,引起我注意的有两种方案。1.微软自带的Microsoft.AspNet.WebApi.HelpPage 2.swagger(我比较喜欢戏称为“丝袜哥”) 最先尝试的是微软自带的方案,由于项目对webapi了一定改造导致使用该方案时一直报错,于是转向了第二种方案,经过大半天大捣鼓,最终效果如下 1.列出所有API控制器和控制器描述 2.列出action和描述 3.直观的接口测试 达到这几点目标,已经满足项目使用。 阅读目录 1.创建webapi项目解决方案 2.引用swagger nuget包 Swashbuckle和Swagger.Net.UI两个包
3.卸载重复包Swagger.Net 引用Swagger.Net.UI时会引用Swagger.Net这个包,但是Swagger.Net的功能和Swashbuckle重复了。所以我采取了卸载Swagger.Net
删除多余的SwaggerUI文件夹
删除多余的配置类SwaggerNet
4.添加接口注释 完成上面三部运行项目,可以看到接口描述已经生成,浏览地址http://xxx/Swagger。但是没有接口的注释,下面添加接口注释 项目属性->勾选生成xml文档文件 修改SwaggerConfig文件 经过上面的操作,已经完成了所需功能。但是还有几点问题需要完善 1.界面的说明都是英文的需要进行汉化 2.控制器没有描述 3.接口过多每次生成速度比较慢 1.汉化步骤 在SwaggerConfig配置文件中有这么一段代码 这段代码的作用是向页面输出引用Swashbuckle.Dummy.SwaggerExtensions.testScript1.js文件,或许会疑问js文件路径为什么这么奇怪。那是因为Swagger将资源文件都嵌入到dll中了,我们常用的资源文件都是以内容的方式放在项目中的,我们也可以以嵌入的资源方式引入到项目中 这也是上面我将SwaggerUI文件夹删除,页面也能正常出来的原因。资源文件都被打包到dll中了,为了验证这个说法,使用反编译工具reflector。来反编译一下Swashbuckle.Core.dll 弄清楚了实现原理,现在来实现汉化。添加自己的中文语言包,和转换js,实现逻辑参考swagger源码。 2.控制器描述和接口文档缓存 上面汉化的js中的方法_setControllerSummary通过读取ControllerDesc属性设置了控制器的描述,至此项目可以无忧使用接口描述文档。 3.使用了MEF导致接口重复问题解决方案 代码请参照项目中的SwaggerConfig_解决MEF重复问题.cs文件 该篇到这里可以结束了,考虑到有的读者想了解更多Swagger的实现内幕,这里再做一下简单的思路引导。 Swagger的读取所有Controller和Action借助于IApiExplorer接口的方法GetApiExplorer,其中IApiExplorer在System.Web.Http中。 有兴趣的可以看一下ApiExplorer.cs源码,使用GlobalConfiguration.Configuration.Services.GetApiExplorer().ApiDescriptions 即可查看所有Api接口地址相关信息,Swagger正是借助于该方法导出所有接口信息,在结合xml文档添加相应注释文成接口描述文档的。 我们可以在Global.asax.cs Application_Start中替换掉系统自带的ApiExploer服务,使用我们自己自定义的服务。 有了这么方便的接口描述文档和接口测试工具,让前后端分离开发更加便于沟通和落地了,测试也可以不依赖于界面单独测试接口,有需要的可以使用起来。本篇所使用示例代码下载地址:SwaggerDemo,参考资源: Swashbuckle:https://github.com/domaindrivendev/Swashbuckle webapi文档描述-swagger 标签:响应 dep 内容 疑问 reflect 说明 inf 警告 ide 原文地址:https://www.cnblogs.com/turnip/p/12335358.html
使用swagger
//c.IncludeXmlComments(GetXmlCommentsPath());
//设置接口描述xml路径地址
c.IncludeXmlComments(string.Format("{0}/bin/SwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));
汉化及问题解决
.EnableSwaggerUi(c =>{
//c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js")
}); //c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js");
//路径规则,项目命名空间.文件夹名称.js文件名称
c.InjectJavaScript(thisAssembly, "SwaggerDemo.Scripts.swaggerui.swagger_lang.js");
///
c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
ApiExplorer思路拓展
public class CustomApiExplorer : ApiExplorer
{
public CustomApiExplorer(HttpConfiguration configuration) : base(configuration)
{
}
public override bool ShouldExploreAction(string actionVariableValue, HttpActionDescriptor actionDescriptor, IHttpRoute route)
{
return base.ShouldExploreAction(actionVariableValue, actionDescriptor, route);
}
public override bool ShouldExploreController(string controllerVariableValue, HttpControllerDescriptor controllerDescriptor, IHttpRoute route)
{
return base.ShouldExploreController(controllerVariableValue, controllerDescriptor, route);
}
}
GlobalConfiguration.Configuration.Services.Replace(typeof(IApiExplorer), new CustomApiExplorer(GlobalConfiguration.Configuration));
总结