Swagger简介
来源:互联网 发布:国家博物馆淘宝 编辑:程序博客网 时间:2024/06/07 22:13
欢迎访问元博客查看原文:http://wangnan.tech
前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
一、使用介绍
什么是 Swagger?
Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。
浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息,包括附加的支持其他语言的库。
如何集成Swagger-springmvc到我们的项目中?
依赖:
Maven
Gradle
使用:
要最快捷地启动swagger-springmvc项目并且使用默认设置,推荐的方式是使用SwaggerSpringMvc插件
Spring Java Configuration
Spring xml Configuration
SwaggerSpringMvcPlugin XML Configuration
为了使用这个插件,你需要创造一个spring Java配置类。使用spring的 @Configuration ,这个配置类必须被定义到你的xml上下文
SwaggerSpringMvcPlugin Spring Java Configuration
使用@EnableSwagger注解
自动注入SpringSwaggerConfig
定义一个或多个SwaggerSpringMvcPlugin实例,通过springs @Bean注解
二、碰到的问题
关于@API注解
在Swagger Annotation中:
在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。
在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。
ApiParam用于描述该API操作接受的参数类型
再接着,为项目的Model对象添加Swagger Annotation,这样Swagger Scanner可以获取更多关于Model对象的信息。
通过上面的步骤,项目已经具备了提供Swagger格式的API信息的能力,接下来,我们把这些信息和Swagger UI集成,以非常美观,实用的方式把这些API信息展示出来。
和Swagger UI的集成
首先,从github(https://github.com/wordnik/swagger-ui)上下载Swagger-UI, 把该项目dist目录下的内容拷贝到项目的resources的目录assets下。
然后,修改index.html, 把Swagger UI对象中的URL替换为自己的API路径。
最后,为了能访问到该页面,还需要在Service的Initialize方法中,添加AssetsBundle
最后的效果图:
三、评价
Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。
Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。
四、参考资料
官网:http://swagger.io/
GitHub:
swagger-springmvc:https://github.com/martypitt/swagger-springmvc
swagger-ui:https://github.com/swagger-api/swagger-ui
swagger-core:https://github.com/swagger-api/swagger-core
swagger-spec:https://github.com/swagger-api/swagger-spec
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger简介
- Swagger SpringMVC整合与简介
- Swagger
- swagger
- swagger
- swagger
- swagger
- 设计,为了更好的应对变化
- android混淆相关
- servlet生命周期
- 设计模式-享元模式
- Activity启动方式
- Swagger简介
- 292.Nim Game
- matlab自带各种分类器的使用示例
- shell脚本统计文件中单词的个数
- MySQL 从外表查询(并截取固定长度)批量插入数据到表中
- window下的redis安装使用
- 海量数据处理
- 延长FLASH和EEPROM芯片写入次数的小方法
- 工具类的封装--Log封装