如何使 WebAPI 自动生成漂亮又实用在线API文档
1.前言
1.1 SwaggerUI
SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用(官方demo)。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。
2.快速开始
创建项目 OnlineAPI来封装百度音乐服务(示例下载) ,通过API可以搜索、获取音乐的信息和播放连接。
我尽量删除一些我们demo中不会用到的一些文件,使其看上去比较简洁。
WebAPI 安装 Swashbuckle
Install-Package Swashbuckle
代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的,生成 SwaggerUI,JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件,用于配置 SwaggerUI 相关展示行为的。如图:
将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在当前类中添加一个方法
/// <summary>/// </summary>/// <param name="name"></param>/// <returns></returns>protected static string GetXmlCommentsPath(string name){ return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name); }
紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”,编译过程中生成类库的注释文件
添加百度音乐 3个API
访问
http://<youhost>/swagger/ui/index
,最终显示效果
我们通过API 测试API 是否成功运行
3.添加自定义HTTP Header
在开发移动端 API时常常需要验证权限,验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可
首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter>();
添加Web权限过滤器
在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]
最终显示效果
4.显示上传文件参数
SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似,只是我们通过特殊的设置来标示API具有上传文件的功能
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter>();
API 文档展示效果
5.版本和资源
你可以通过下列连接获取相关说明。
OnlineAPI Demo 项目下载
OnlineAPI Demo下载
Swashbuckle 项目地址:
https://github.com/domaindrivendev/Swashbuckle
swagger-ui 项目地址:
https://github.com/swagger-api/swagger-ui
swagger-ui 官网地址:
http://swagger.io/swagger-ui/
相关文章:
WebAPI前置知识:HTTP与RestfulAPI
WEB API系列(一):WEB API的适用场景、第一个实例
WEB API 系列(二) Filter的使用以及执行顺序
ASP.NET Web API 安全筛选器
Web API 基于ASP.NET Identity的Basic Authentication
ASP.NET Web Api使用CacheCow和ETag缓存资源
使用 West Wind WebSurge 对 ASP.NET Web API 服务进行压力测试
Web API应用支持HTTPS的经验总结
Dion Hinchcliffe谈Web API的过去与未来
WebAPI生成可导入到PostMan的数据
原文地址:http://www.cnblogs.com/Arrays/p/5146194.html
.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注
赞赏
人赞赏
如何使 WebAPI 自动生成漂亮又实用在线API文档相关推荐
- 第十二节:WebApi自动生成在线Api文档的两种方式
一. WebApi自带生成api文档 1. 说明 通过观察,发现WebApi项目中Area文件夹下有一个HelpPage文件夹,如下图,该文件夹就是WebApi自带的生成Api的方式,如果该文件夹没了 ...
- Eclipse 如何生成项目的javadoc(API 文档)
文章目录 生成 javadoc 的三种方法 乱码问题 生成 javadoc 的三种方法 1.在项目列表中按右键,选择 Export,然后在 Export 对话框中选择 Java 下的 Javadoc, ...
- 自动生成代码的chm格式帮助文档
在Visual Studio下编程,有两个很方便的生成chm帮助文档的工具.它们就是Sandcastle Help File Builder 和Sandcastle.Sandcastle Help F ...
- python连接mysql,自动生成数据库表对应的word文档(毕设福利)
效果图 运行程序后生成的word文档 所需依赖 安装两个依赖插件 pip install pymysql pip install python-docx python程序 #!/usr/bin/pyt ...
- php 在线api文档生成,api在线管理,调试,文档生成工具之Apizza
摘要: Apizza (http://apizza.cc?f=bl) 是国内领先的在线API saas 管理平台,支持在线的API调试,接口管理,快速生成文档,项目管理以及分享. 平台分为开发模式和浏 ...
- 使用swagger实现在线api文档自动生成 在线测试api接口
使用vs nuget包管理工具搜索Swashbuckle 然后安装便可 注释依赖于vs生成的xml注释文件 转载于:https://www.cnblogs.com/ProDoctor/p/752607 ...
- SpringBoot整合Swagger 自动生成在线API文档 偷懒必备 同时也是我们的基本操作啦!!!
不知道哦昨天的七夕过的咋样,总之我就是在这new GirlFriend().在那netw GirlFriend(),就这样度过了一天.
- c语言如何自动生成word,C语言读取word文档的方法
C语言读取word文档的方法 第一种方法: 复制代码 代码如下: Response.ClearContent(); Response.ClearHeaders(); Response.ContentT ...
- IntelliJ IDEA forMac 如何生成项目的javadoc(API文档)
1.在菜单栏,点击 Tools -> Generate JavaDoc- 2.根据你自己的需要,设置解析源文件的范围.设置文档输出目录.设置资源的访问权限范围.字符编码.堆内存大小等.
最新文章
- Google Brain 研究员梁辰:从零开始搜索机器学习算法(附视频、PPT)
- 从Deepwalk到Node2vec
- 信号与系统奥本海姆pdf_2019上海交通大学819信号系统与信号处理考研初/复试经验...
- js php 时间格式化字符串,JS怎么实现字符串与日期的互相转换及日期的格式化
- 开放共赢,华为云WeLink生态联盟正式成立!
- 信息学奥赛一本通 1020:打印ASCII码 | OpenJudge NOI 1.2 07
- Java教程:Java字符串替换实例
- C++并发与多线程(五)互斥量,atomic、与线程池
- android特殊用法(转)
- 碳中和数据集 1991-2020全球中国省级地级市县级市区各行业碳中和二氧化碳排放量碳封存 能源消费能源消耗能源结构数据大全
- 聊天室 作业 java_java大作业设计报告-java聊天室.docx
- java js css 压缩工具_JSCSS压缩工具YUICompressor
- 怎么免费提取PDF页面?
- 第五届蓝桥杯 软件类省赛真题 第八题:兰顿蚂蚁
- 【毕业设计】基于单片机的宠物自动喂食系统 - 物联网 嵌入式 单片机 宠物喂食系统 宠物投食系统
- 第二章:如何撰写学术论文(文科)
- Element UI中Steps 步骤条description描述换行展示
- 移动端H5(JavaScript)识别二维码功能
- MS开始提供Windows Vista beta2下载
- android打电话播放录音,安卓原生的拨号器应用通话录音功能已经到来但暂时还不能正常使用...
热门文章
- windows server 2012 dhcp 配置故障转移
- jquery实现多行滚动效果
- selenium webdirver之ruby-开发ide安装
- 使用Blazor做个简单的时间戳在线转换工具
- 基于PaddleOCR实现AI发票识别的Asp.net Core应用
- iNeuOS 工业互联网操作系统,在核工业测控领域的成功应用
- 什么是ASP.NET Core静态Web资产?
- .NET Core开发实战(第25课:路由与终结点:如何规划好你的Web API)--学习笔记(下)...
- 用ASP.NET Core构建可检测的高可用服务--学习笔记
- 博客园升级有感一点建议