Webapi文档描述-swagger优化
作者:jianxuanbing
本文为作者原创,转载请注明出处:https://www.cnblogs.com/jianxuanbing/p/7376757.html
一、前言
最近做的项目使用WebApi
,采取前后端分离的方式,后台提供API
接口给前端开发人员。这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用word
、Xmind思维导图
方式进行交流,实际操作中却很少动手去写。为了解决这个问题,特意在博客园搜索了一下api
接口文档生成的文章,引起我注意的有以下两种方案。
- 微软自带的
Microsoft.AspNet.WebApi.HelpPage
Swagger(丝袜哥)
但是在使用过程中微软自带的没有Swagger
直观,因此采用了第二种方案Swagger
。
二、问题
在使用swagger的过程中,产生了一些小问题,例如:汉化
、查询
、控制器备注
。
在博客园当中找到了相关的解决方式,但是汉化、控制器备注会产生二次请求的问题,尤其在接口比较多的情况下,还是比较慢的。因此产生了修改swagger-ui
和Swashbuckle
源码的念头。
三、效果图
3.1 汉化效果
3.2 控制器注释以及接口数量统计
3.3 查询
四、如何使用
4.1 创建Webapi项目解决方案
4.2 引用SwashbuckleEx
nuget包
SwashbuckleEx
和SwashbuckleEx.Core
这两个包
4.3 添加接口注释
完成上面2部运行项目,可以看到接口描述已经生成,浏览地址http://xxxx/swagger
。但是没有接口的注释,下面添加接口注释。
4.3.1 项目属性->勾选生成xml文档文件
注:如果实体与Api库分开,那么需要在实体库也勾选上生成xml文件,并设置文件名称(默认名称即可)。
4.3.2 修改SwaggerConfig.cs
文件
c.SingleApiVersion("v1", "xxx");
c.IncludeXmlComments(string.Format("{0}/bin/xxx.Api.XML", AppDomain.CurrentDomain.BaseDirectory));
给接口添加注释,即可看到参数与方法描述了。
4.3.3 配置Web.config
文件
有园友提出使用Nuget包后,展示是空的,因此看了下,需要配置一下以下的内容即可。
<system.webServer>
<modules runAllManagedModulesForAllRequests="true">
<remove name="WebDAVModule" />
</modules>
</system.webServer>
五、源码地址
Github:https://github.com/jianxuanbing/SwashbuckleEx.git
六、总结
修改Swashbuckle
源码过程中,踩的坑还是比较多的,这个后续开一篇文章进行说明实现上述的功能。
有了汉化、控制器注释、接口数量统计、查询,加快的前后端开发的对接。
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· PostgreSQL 和 SQL Server 在统计信息维护中的关键差异
· C++代码改造为UTF-8编码问题的总结
· DeepSeek 解答了困扰我五年的技术问题
· 为什么说在企业级应用开发中,后端往往是效率杀手?
· 用 C# 插值字符串处理器写一个 sscanf
· [翻译] 为什么 Tracebit 用 C# 开发
· Deepseek官网太卡,教你白嫖阿里云的Deepseek-R1满血版
· DeepSeek崛起:程序员“饭碗”被抢,还是职业进化新起点?
· 2分钟学会 DeepSeek API,竟然比官方更好用!
· .NET 使用 DeepSeek R1 开发智能 AI 客户端