使用Swagger 搭建高可读性ASP.Net WebApi文档

一、前言#

在最近一个商城项目中,使用WebApi搭建API项目。但开发过程中,前后端工程师对于沟通接口的使用,是非常耗时的。之前也有用过Swagger构建WebApi文档,但是API文档的可读性并不高。尤其是没有传入参数和传出结果的说明,导致开发人员沟通困难。在园子里看到一篇关于对Swagger优化的文章,有很大的改进。解决了传入参数,API分区域筛选等问题, 非常感谢博主简玄冰

不过实践之后,发现还有些问题未解决:

  1. 接口返回的对象,没有汉化说明
  2. 接口授权参数(token)未统一传入

所以,决定在此基础上,再进行一些优化

二、效果图#

1. 分区域展示#

2.接口参数说明#

   

3.授权参数统一传入 token#

   

4.接口查询#

5.接口开发状态#

   

三、关键实现#

1.项目属性设置生成xml文档文件#

   

2.修改SwaggerConfig.cs文件#

   

3. 修改WebApiConfig.cs文件,配置路由#

   

4.分区域筛选关键逻辑#

 需要注意: 实现逻辑与命名空间的分割符. 有很大关系,具体请查看文件SwaggerAreasSupportDocumentFilter.cs

 

   

四、Demo源码地址#

 Github: https://github.com/yinboxie/Swagger-Demo.git

 下载demo源码后,如果发现不能自动下载nuget依赖包,请执行命令Update-Package -ProjectName 'swagger.demo.api' -Reinstall

 启动项目之后,访问地址http://localhost:11008/apis/index

五、总结#

Swashbuckle 源码是没有注释说明,比较难以阅读。我也只是在大神简玄冰的基础上,修改了几处Swashbuckle 源码。

改动之后的Swashbuckle 源码 Github: https://github.com/yinboxie/SwashbuckleEx.git

六、参考#

posted @   沉淀的风  阅读(1361)  评论(11编辑  收藏  举报
编辑推荐:
· PostgreSQL 和 SQL Server 在统计信息维护中的关键差异
· C++代码改造为UTF-8编码问题的总结
· DeepSeek 解答了困扰我五年的技术问题
· 为什么说在企业级应用开发中,后端往往是效率杀手?
· 用 C# 插值字符串处理器写一个 sscanf
阅读排行:
· [翻译] 为什么 Tracebit 用 C# 开发
· Deepseek官网太卡,教你白嫖阿里云的Deepseek-R1满血版
· 2分钟学会 DeepSeek API,竟然比官方更好用!
· .NET 使用 DeepSeek R1 开发智能 AI 客户端
· 刚刚!百度搜索“换脑”引爆AI圈,正式接入DeepSeek R1满血版
点击右上角即可分享
微信分享提示
CONTENTS