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

1、前言

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

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

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

因此，决定在此基础上，再进行一些优化

2、效果图

1. 分区域展现

2.接口参数说明

   

3.受权参数统一传入 token

   

4.接口查询

5.接口开发状态

   

3、关键实现

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

   

2.修改SwaggerConfig.cs文件

   

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

   

4.分区域筛选关键逻辑

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

 

   

4、Demo源码地址

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

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

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

5、总结

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

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

6、参考

• Webapi文档描述-swagger优化