Swagger使用总结
Swagger使用总结
1. Swagger是什么?
官方说法:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
个人觉得,swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中,发生过多次:修改代码但是没有更新文档,前端还是按照老旧的文档进行开发,在联调过程中才发现问题的情况(当然依据开闭原则,对接口的修改是不允许的,但是在项目不稳定阶段,这种情况很难避免)。
2. spring boot 集成 Swagger
目前维护的系统是基于springboot框架开发的,因此本文会详细描述springboot与swagger集成的过程。
spring-boot系统集成swagger需要进行如下操作:
添加maven依赖,需要在系统的pom中添加如下依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
添加swagger配置文件,配置文件如下:
@Configuration@EnableSwagger2
public class SwaggerConfig { @Beanpublic Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select() // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.any()) // 对所有api进行监控
.paths(PathSelectors.any()) // 对所有路径进行监控
.build();
} }通过注解EnableSwagger2声明Swagger的可用性,此处会定义一个类型为Docket的bean,
关于docket类的说明如下:A builder which is intended to be the primary interface into the swagger-springmvc framework.Provides sensible defaults and convenience methods for configuration.
Docket的select()方法会提供给swagger-springmvc framework的一个默认构造器(ApiSelectorBuilder),这个构造器为配置swagger提供了一系列的默认属性和便利方法。
测试
通过访问:http://localhost:8080/your-app-root/v2/api-docs ,能测试生成的api是否可用。此时返回的是一个json形式的页面,可读性不好。可以通过Swagger UI来生成一个可读性良好的api页面。具体做法就是,在pom中添加相关依赖。如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
再次访问:http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可读性较好的api文档页面。
注意:
- http://localhost:8080/your-app-root/v2/api-docs 中your-app-root指的你的wabapp的根路径,我目前的webapp就默认在根路径下,所以地址是:http://localhost:8080/v2/api-docs
- spring-mvc上引用swagger需要做其他相关的配置,具体请查看参考文献
- swagger对restful风格的api支持的比较好,非restful风格的api支持的不是很好,对于非restful风格的api或者其他语言(非java语言)可以采用http://editor.swagger 编辑器来收工完成相关的API编写
参考文献
Swagger使用总结的更多相关文章
- ABP框架 - Swagger UI 集成
文档目录 本节内容: 简介 Asp.net Core 安装 安装Nuget包 配置 测试 Asp.net 5.x 安装 安装Nuget包 配置 测试 简介 来自它的网页:“...使用一个Swagger ...
- ABP项目中使用Swagger生成动态WebAPI
本文是根据角落的白板报的<使用ABP实现SwaggerUI,生成动态webapi>一文的学习总结,感谢原文作者角落的白板报. 1 安装Swashbuckle.core 1.1 选择WebA ...
- 用Swagger生成接口文档
Swagger简介 在系统设计的时候,各个应用之间往往是通过接口进行交互的.因此接口的定义在整个团队中就变得尤为重要.我们可以把接口的规范用接口描述语言进行描述,然后Swagger可以根据我们定义的接 ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- 使用swagger作为restful api的doc文档生成
初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...
- ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档
原文:ASP.NET Web API Help Pages using Swagger 作者:Shayne Boyer 翻译:谢炀(kiler) 翻译:许登洋(Seay) 对于开发人员来说,构建一个消 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- ASP.NET WebApi 文档Swagger深度优化
本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明博客园蜗牛原文地址,cnblogs.com/tdws 写在前面 请原谅我这个标题党,写到了第100篇随笔,说是深度优化,其实也并没有什么深度 ...
- ASP.NET WebApi 文档Swagger中度优化
本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明原文地址:www.cnblogs.com/tdws 写在前面 在后台接口开发中,接口文档是必不可少的.在复杂的业务当中和多人对接的情况下,简 ...
- NSwagStudio for Swagger Api
本案例主要说明如何使用NSwag 工具使用桌面工具快速生成c# 客户端代码.快速的访问Web Api. NSwagStudio 下载地址 比较强大.可以生成TypeScript.WebApi Cont ...
随机推荐
- 6/13 Sprint2 看板和燃尽图
部分页面展示
- jQuery1.9为动态添加元素绑定事件以及获取和操作checkbox的选择属性
1.jQuery为动态添加的元素绑定事件:在1.7之后,添加了live()方法,1.9后又被移除,1.9中可用on()方法: $(function() { $('.btn').on('click', ...
- LoarRunner11使用异常及解决方案
1:使用VuGen录制后出现“由于另一个程序正在运行中,此操作无法完成.请选择切换到来激活正在运行中的程序,并更正问题”,点击“切换到”无效果. 解决:在“运行”中输入“msconfig”,选择“启用 ...
- 给一个div绝对定位后,如何让它水平居中
<style> .footer{position:absolute;left:0;right:0} </style> <div classs="footer&q ...
- App压力测试整理
压力测试结果:CRASH:崩溃,应用程序在使用过程中,非正常退出ANR:Application Not Responding MonkeyRunner APIs MonkeyRunner:用来连接设备 ...
- 用MySQL实现分页查询
MySQL中实现分页查询语句: //定义分页需要的变量 int pageNow=2;//当前页 int pageSize=3;//指定每页显示3条记录 int pageCount=1;//该值是计算出 ...
- WCF初探-15:WCF操作协定
前言: 在前面的文章中,我们定义服务协定时,在它的操作方法上都会加上OperationContract特性,此特性属于OperationContractAttribute 类,将OperationCo ...
- 我原来忽略的web开发点
打开一个网页,看到的东西的背后还有看不见的东西,程序员通常在一个页面影藏了许多标签,这个页面可以用来在许多地方使用,因为模板相同,只是有点地方不一样.还有类似于新浪微博的页面使用了很多花样,消息推送( ...
- HTML中head里的内容经浏览器解析后全到body里
我从linux服务器nginx上把一个网站迁移到windows的IIS上数据什么的都么有问题,配置好rewrite以后,访问网站,发现样式变动了,网站上方空出了一块我用chrome浏览器的审查元素一看 ...
- C语言基础--数组及相关
概念: 一堆相同类型的数据的有序集合 格式: 元素类型 数组名称[ 元素个数 ] 定义数组: // 定义了一个名称叫做scores的数组, 数组中可以存放3个int类型的数据 ]; // 只要定义一 ...