第十二节:WebApi自动生成在线Api文档的两种方式
一. WebApi自带生成api文档
1. 说明
通过观察,发现WebApi项目中Area文件夹下有一个HelpPage文件夹,如下图,该文件夹就是WebApi自带的生成Api的方式,如果该文件夹没了,可以通过Nuget安装:Microsoft.AspNet.WebApi.HelpPage ,你就会发现下图这一坨代码又回来了。
使用:http://localhost:2131/Help/Index , 即可访问生成的Api目录,如下图:
缺点:你会发现一个很坑爹的问题,方法名的注释和参数的注释均不显示,这对使用者而言,相当不放方便了。
2. 改进支持参数的注释
(1). 选中项目,右键属性,填写生成xml文件的路径,如下图: bin\api.xml
(2). 找到 Areas/HelpPage/App_Start 目录下的HelpPageConfig.cs 文件,Register 方法,添加一行代码:
config.SetDocumentationProvider(new XmlDocumentationProvider(AppDomain.CurrentDomain.BaseDirectory + "bin\\api.xml"));
(3). 大功告成,再次访问 http://localhost:2131/Help/Index ,发现无论是方法名还是参数名,均有描述了
3. 小结
上述通过改进,已经生成比较完善的Api文档了,但美中不足的是不能直接测试,当然可以整合别的控件使其支持,但比较麻烦,不如使用下面的SwashBuckle生成SwaggerUI形式的Api文档。
二. 借助SwaggerUI生成api文档
1. 通过Nuget安装 Swashbuckle (版本:5.6.0)程序集,会发现在 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件,用于配置 SwaggerUI 相关展示行为的,如下图:
(2). 选中项目,右键属性,勾上xml文档文件,注意:这里默认是什么就保留什么,不要在自己改了 。如下图: bin\05-WebApiExtend.xml
(3). 在SwaggerConfig.cs文件中 搜索 【 c.IncludeXmlComments(GetXmlCommentsPath()); 】,在这句话的下面新增一句代码:
c.IncludeXmlComments(AppDomain.CurrentDomain.BaseDirectory + "bin\\05-WebApiExtend.xml");
(4). 大功告成,访问:http://localhost:2182/swagger/ui/index ,即可查看生成Api文档。
!
- 作 者 : Yaopengfei(姚鹏飞)
- 博客地址 : http://www.cnblogs.com/yaopengfei/
- 声 明1 : 本人才疏学浅,用郭德纲的话说“我是一个小学生”,如有错误,欢迎讨论,请勿谩骂^_^。
- 声 明2 : 原创博客请在转载时保留原文链接或在文章开头加上本人博客地址,否则保留追究法律责任的权利。
第十二节:WebApi自动生成在线Api文档的两种方式的更多相关文章
- 使用jsdoc-toolkit来自动生成js api文档
近来前端组小盆友开发的类库越来越多,很多情况下彼此不知道写了些什么方法,为了更好的合作提高工作效率,找了个比较好的api文档生成方法.使用jsdoc-toolkit来自动生成js api文档. 一. ...
- WebApi生成在线API文档--Swagger
1.前言 1.1 SwaggerUI SwaggerUI 是一个简单的Restful API 测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON 配置显示API. 项目本身仅仅也只依赖 ...
- Golang使用swaggo自动生成Restful API文档
#关于Swaggo 相信很多程序猿和我一样不喜欢写API文档.写代码多舒服,写文档不仅要花费大量的时间,有时候还不能做到面面具全.但API文档是必不可少的,相信其重要性就不用我说了,一份含糊的文档甚至 ...
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
- Go学习笔记(六) | 使用swaggo自动生成Restful API文档(转)
关于Swaggo 或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分.只要通过一个命令就可以将注释转换成文档,这让我们可以更加专注于代码. 目前swaggo主要实现了sw ...
- C# 自动生成代码API文档
暂时没学会正规的转载style临时记录一下 NET中的规范标准注释(一) -- XML注释标签讲解 http://www.cnblogs.com/mq0036/p/3544264.html NET中的 ...
- jsdoc注释规范工具(使用 JSDoc 3 自动生成 JavaScript API 文档)
安装和使用规范见:http://moodpo.com/archives/jsdoc3-tutorial.html 实例: /** * 模块调用方法 * * * @param {string} modu ...
- spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
spring boot / cloud (三) 集成springfox-swagger2构建在线API文档 前言 不能同步更新API文档会有什么问题? 理想情况下,为所开发的服务编写接口文档,能提高与 ...
- 使用swagger来编写在线api文档
swagger是一个非常简单,强大的框架.快速上手,只需要引入jar包 , 使用注解就可以生成一个漂亮的在线api文档 pom.xml <dependency> <groupId&g ...
随机推荐
- JavaScript jQuery 中定义数组操作及数组操作
1.认识数组 数组就是某类数据的集合,数据类型可以是整型.字符串.甚至是对象 Javascript不支持多维数组,但是因为数组里面可以包含对象(数组也是一个对象),所以数组可以通过相互嵌套实现类似多维 ...
- Status bar could not find cached time string image. Rendering in-process?
在开发中,控制台经常输出“Status bar could not find cached time string image. Rendering in-process?” 在 Info.plist ...
- Windows Server 2016-Windows安全日志ID汇总
Windows常见安全事件日志ID汇总,供大家参考,希望可以帮到大家. ID 安全事件信息 1100 事件记录服务已关闭 1101 审计事件已被运输中断. 1102 审核日志已清除 1104 安全日志 ...
- java编译过程中出现了Exception in thread “main" java.lang.UnsupportedClassVersionError
原因:这个问题确实是由较高版本的JDK编译的java class文件试图在较低版本的JVM上运行产生的错误. 以下是报错截图: 1.解决措施就是保证jvm(java命令)和jdk(javac命令)版本 ...
- 安装mysql8.0.12
安装mysql8.0.12 https://blog.csdn.net/zwj1030711290/article/details/80039780 问题1:忘记记录日志打印的密码就把窗口给关了 解决 ...
- 数据库【mongodb篇】练习操作
本文的目标是通过大量的示例,来更好的理解如果在Mongodb中进行数据操作: 初入客户端刚利用 mongod命令进入客户端环境,此时对数据库一无所知: 举目四望,想知道现在有哪些数据库, show ...
- CMake与Make最简单直接的区别 [转]
写程序大体步骤为: 1.用编辑器编写源代码,如.c文件. 2.用编译器编译代码生成目标文件,如.o. 3.用链接器连接目标代码生成可执行文件,如.exe. 但如果源文件太多,一个一个编译时就会特别麻烦 ...
- C++ 精英化趋势
精英化趋势 C++ 是一门引起无数争议的语言.眼下最常听到的声音则是 C++ 将趋于没落,会被某某语言取代.我很怀疑这种论调的起点是商业宣传,C++ 的真实趋势应该是越来越倾向于精英化. 精英化是指在 ...
- QTableWidget class
Help on class QTableWidget in module PyQt5.QtWidgets: class QTableWidget(QTableView) | QTableWidge ...
- Win 7/10 安装Oracle 11g
两个系统安装oracle的过程基本一致,注意安装时选桌面类(没有试过server,只有server类的操作系统选择server类) 安装过程:https://jingyan.baidu.com/alb ...