Swagger配置手记
来源:互联网 发布:ubuntu 优麒麟 编辑:程序博客网 时间:2024/06/07 03:29
前言
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 springMVC,配置
- Swagger配置(SpringMVC、SpringBoot)
- springmvc 配置swagger
- SpringBoot配置Swagger
- Security配置swagger
- gradle项目swagger配置
- springmvc4 spring4 swagger配置问题
- springMVC+jetty+swagger 简单配置
- Swagger配置:Maven+SpringBoot+jdk1.
- SpringMVC 中配置 Swagger 插件
- webapi 配置swagger出现问题:not supported by swagger 2.0
- Swagger
- swagger
- swagger
- swagger
- windows系统下git的安装
- OKHTTP
- spark core 2.0 LongArray
- BZOJ1027: [JSOI2007]合金
- man使用手册
- Swagger配置手记
- Android源码编译教程之环境搭建
- Leetcode 441. Arranging Coins
- POJ 1390 Blocks (DP)
- Dell 7559 安装Ubuntu以及Nvidia 960M驱动相关问题及解决
- Linux C++ 初次尝试 单链表
- ice Callback
- SecureCRT 7.2.0 Mac版密码无法保存的解决办法
- Eclipse中导入项目后js报错解决方法