使用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

六、参考

原文地址:https://www.cnblogs.com/xyb0226/p/9500633.html

时间: 2024-10-03 01:41:20

使用Swagger 搭建高可读性ASP.Net WebApi文档的相关文章

ASP.NET WebApi 文档Swagger深度优化

本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明博客园蜗牛原文地址,cnblogs.com/tdws 写在前面 请原谅我这个标题党,写到了第100篇随笔,说是深度优化,其实也并没有什么深度.源码也没怎么修改,如果你想使用WebApi Swagger文档,请先移步到上一篇的中度优化. 第一篇:ASP.NET WebApi 文档Swagger中度优化 http://www.cnblogs.com/tdws/p/6100126.html 第二篇:ASP.NET WebApi 文档Swashbu

ASP.NET WebApi 文档Swagger中度优化

本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明原文地址:www.cnblogs.com/tdws 写在前面 在后台接口开发中,接口文档是必不可少的.在复杂的业务当中和多人对接的情况下,简单的接口文档又不能满足需求,试想你的单应用后台有几十个模块,几百甚至更多的接口,又有上百个ViewModel.怎么能让人用起来更顺手更明了?本篇介绍第一步的中度优化,下一篇将分享下一阶段的深度优化. 第一篇:ASP.NET WebApi 文档Swagger中度优化 1.上手使用 2.Controller

WebApi 文档Swagger

NET WebApi 文档Swagger中度优化 本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明原文地址:www.cnblogs.com/tdws 写在前面 在后台接口开发中,接口文档是必不可少的.在复杂的业务当中和多人对接的情况下,简单的接口文档又不能满足需求,试想你的单应用后台有几十个模块,几百甚至更多的接口,又有上百个ViewModel.怎么能让人用起来更顺手更明了?本篇介绍第一步的中度优化,下一篇将分享下一阶段的深度优化. 第一篇:ASP.NET WebApi 文档Swagge

PCB DotNetCore Swagger生成WebAPI文档配置方法

在.net framework框架下可以使用WebApiTestClientWebApi生成WebAPI接口文档与方便接口测试用,而在DotnetCore却没有找到这个工具了,baidu查找一下发现有一个相类似的工具,它就是Swagger,和使用WebApiTestClientWebApi差不多的,这里Swagger配置过程整理如下:   一.下载Swashbuckle.AspNetCore NuGet下载安装Swashbuckle.AspNetCore   二.Startup.cs代码修改 1

Taurus.MVC 2.3 开源发布:增强属性Require验证功能,自带WebAPI文档生成功能

背景: 上周,把 Taurus.MVC 在 Linux (CentOS7) 上部署任务完成后. 也不知怎么的,忽然就想给框架集成一下WebAPI文档功能,所以就动手了. 以为一天能搞完,结果,好几天过去了. 本来还想集成自动化批量执行测试功能,不过想想还是放到下一版本实现吧. 感觉差不多了,就先和大伙分享一下: Taurus.MVC Nuget 更新: 昨夜,Nuget的Package升级了一下,和源码版本做了下同步. 通常源码的版本都会比Nuget包的靠前一个小版本: 目前:Taurus.MV

线上测试高可用集群部署文档【我的技术我做主】

线上测试高可用集群部署文档 目录: 目录:1 项目需求:2 实现方式:2 拓扑图:3 系统及软件版本:3 安装步骤:4 IP分配:4 LVS和keepalived的安装和配置:4 LVS主配置:4 LVS2备 配置:7 web服务器配置9 Mysql-MHA高可用:13 Mysql主配置:13 manager管理端操作:15 VIP切换:16 测试:26 下面是centos5.6的系统环境,如果是centos6版本,只需改动少许地方即可,步骤一致 . ---- by 金戈铁马行飞燕 项目需求:

springBoot 整合 swagger 展示返回对象的嵌套属性文档注释

spring boot 处理 swagger 嵌套数据展示 在开发的过程中,我们会常常使用swagger做我们的在线文档.我们会在对象的属性上使用@ApiModelProperty 等api注解,但是遇到对象嵌套的时候,如何返回一个嵌套的json文档就需要我们做一些简单的处理 如果只在对象某个属性上使用 @ApiModelProperty 并不会起作用 12345678910111213141516171819202122232425262728293031 @Data@Slf4j@Builde

webapi文档描述-swagger

最近做的项目使用mvc+webapi,采取前后端分离的方式,后台提供API接口给前端开发人员.这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用word文档方式进行交流,实际操作中却很少动手去写.为了解决这个问题,特意在博客园中搜索了一下api接口文档生成的文章,引起我注意的有两种方案.1.微软自带的Microsoft.AspNet.WebApi.HelpPage  2.swagger(我比较喜欢戏称为“丝袜哥”) 最先尝试的是微软自带的方案,由于项目对webap

Swagger生成WebAPI文档

最近在做WebAPI2.0 项目,为了使用者能轻易查看API文档,因此使用Swagger进行了配置 1.打开程序包管理控制台输入: Install-Package Swashbuckle 2.在对应项目里的App_Start文件夹下的SwaggerConfig.cs文件找到: c.IncludeXmlComments 然后进行替换 c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); 3.然后再与Regist