asp.net mvc 集成swagger并汉化文档

之前用.net5.0写webapi,自动集成swagger,非常方便。asp.net mvc没有自动集成swagger,但是手动配置swagger也很简单。
1、nuget引用Swashbuckle库,安装完后,App_Start下自动多了一个SwaggerConfig.cs;
2、打开SwaggerConfing.cs,
c.SingleApiVersion("v1", "××系统API"); 这行是标记api的名字
c.IncludeXmlComments(GetXmlCommentsPath()); 这行是加载xml描述
c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, string.Format(@"{0}\bin\WRSServices.XML", System.AppDomain.CurrentDomain.BaseDirectory)));这行是汉化用的,这个provider里是按照类的summary和xml的member标记解析类,用于解析swagger的模型等,
c.InjectJavaScript(System.Reflection.Assembly.GetExecutingAssembly(), "×××.××.swagger_chs.js");这行是加载swagger汉化的js,js文件属性改为嵌入式资源,js前面以namespace和js所在文件夹的位置为类名称。

注意:
1、项目的属性-【生成】,需要勾上XML文档文件;
2、发布时项目的XML文档文件不会自动发布,需要从bin里拷贝到发布后文件中;
3、要想响应类模型有解析,需要在api方法前加上ResponseType特性,如:
[ResponseType(typeof(×××.×××.ClassName))]
4、api的控制器中不要有泛型类,否则,编译成功,但swagger页面会报错,因为swagger是一开始就需要明确类型,泛型是运行时才知道真是类型,如果需要通过泛型去做一些模式重构的话,可以把泛型的方法单独拎出来,放到helper或公共类里。

SwaggerCacheProvider和swagger的汉化js,网上很多。比如:https://blog.csdn.net/qq_25405005/article/details/89384555

posted @ 2022-04-15 22:43  GIS民工  阅读(389)  评论(0编辑  收藏  举报