springMvc+swagger整合例子
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API与接口方法,参数等保存同步,大大减少了接口开发人员的工作量.这个例子是我本地运行正常的,完整demo在文章最后。
第一步:在pom.xml引入相关jar
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>2.4.0</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>2.4.0</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-core</artifactId>
- <version>2.8.0</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>2.6.3</version>
- </dependency>
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-annotations</artifactId>
- <version>2.6.3</version>
- </dependency>
第二步:配置spring-servlet.xml
- <!-- 激活@controller模式 -->
- <mvc:annotation-driven />
- <!-- 配置包扫描位置(会在此包下扫描@controller控制器) -->
- <context:component-scan base-package="com.scan,com.bean" />
- <!-- swagger静态文件路径 -->
- <mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/" cache-period="31556926"/>
- <mvc:default-servlet-handler />
- <bean class="com.scan.config.SwaggerConfig" />
第三步:编写SwaggerConfig
- package com.scan.config;
- import com.google.common.base.Predicate;
- import org.springframework.beans.factory.annotation.Autowired;
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.ComponentScan;
- import org.springframework.context.annotation.Configuration;
- import org.springframework.web.servlet.config.annotation.EnableWebMvc;
- import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
- import springfox.documentation.service.ApiInfo;
- import springfox.documentation.service.Contact;
- import springfox.documentation.spi.DocumentationType;
- import springfox.documentation.spring.web.plugins.Docket;
- import springfox.documentation.swagger2.annotations.EnableSwagger2;
- import java.util.List;
- import static com.google.common.base.Predicates.or;
- import static com.google.common.collect.Lists.newArrayList;
- @Configuration
- @EnableSwagger2
- @ComponentScan(basePackages = {"com.scan.controller"})
- @EnableWebMvc
- public class SwaggerConfig extends WebMvcConfigurationSupport {
- @Bean
- public Docket customDocket() {
- //
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo());
- }
- private ApiInfo apiInfo() {
- Contact contact = new Contact("老王", "https://www.baidu.me", "baidu_666@icloud.com");
- return new ApiInfo("Blog前台API接口",//大标题 title
- "Swagger测试demo",//小标题
- "0.0.1",//版本
- "www.baidu.com",//termsOfServiceUrl
- contact,//作者
- "Blog",//链接显示文字
- "https://www.baidu.me"//网站链接
- );
- }
- }
第四步:控制层的配置
- @Controller
- @RequestMapping("/userController")
- @Api(tags = "二:用户信息") //swagger分类标题注解
- public class UserController {
- @RequestMapping(value = "/listCompound", method = RequestMethod.GET)
- @ResponseBody
//swagger返回值注解- @ApiResponses(value = {
- @ApiResponse(code = 500, message = "系统错误"),
- @ApiResponse(code = 200, message = "0 成功,其它为错误,返回格式:{code:0,data[{}]},data中的属性参照下方Model", response = UserVo.class) })
- @ApiOperation(httpMethod = "GET", value = "个人信息")//swagger 当前接口注解
- public String listCompound(
- @ApiParam(required = true, name = "start", value = "start") int start,
- int limit,
- @ApiParam(required = false, name = "userName", value = "名称模糊查询") String userName) {
- List<UserVo> data = new ArrayList<UserVo>();
- String msg = data.size() > 0 ? "" : "没有查询到相关记录";
- Result result = new Result();
- result.setMsg(msg);
- result.setCode(0);
- result.setData(data);
- return JSONObject.toJSONString(result);
- }
第五步:下载swaggerUi,将下载后的文件解压,将dist目录下的文件,复制到webapp下的swagger目录中(这个目录的名字自定义,但要和spring-servert.xml中(<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/") 的名称要一致,修改index.html中文档加载的地址.
- window.onload = function() {
- // Build a system
- const ui = SwaggerUIBundle({
- //url: "http://petstore.swagger.io/v2/swagger.json",
- url:"http://127.0.0.1:8080/swagger-spring/v2/api-docs.do",
- dom_id: '#swagger-ui',
- deepLinking: true,
- presets: [
- SwaggerUIBundle.presets.apis,
- SwaggerUIStandalonePreset
- ],
- plugins: [
- SwaggerUIBundle.plugins.DownloadUrl
- ],
- layout: "StandaloneLayout"
- })
如果以上配置正确,在浏览器中输入http://127.0.0.1:8080/swagger-spring/swagger/index.html,将会出现如下界面:
swagger注解说明
1、与模型相关的注解,用在bean上面
@ApiModel:用在bean上,对模型类做注释;
@ApiModelProperty:用在属性上,对属性做注释
2、与接口相关的注解
@Api:用在controller上,对controller进行注释;
@ApiOperation:用在API方法上,对该API做注释,说明API的作用;
@ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明;
@ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:
paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。
name:参数名;
dataType:参数类型,可以是基础数据类型,也可以是一个class;
required:参数是否必须传;
value:参数的注释,说明参数的意义;
defaultValue:参数的默认值;
@ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;
@ApiResponse:用在@ApiResponses中,一般用于表达一个响应信息
code:即httpCode,例如400
message:信息,例如"操作成功"
response = UserVo.class 这里UserVo是一个配置了@ApiModel注解的对像,该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置,生 成接口返回值
- 为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
- 即使只有一个@ApiResponse,也需要使用@ApiResponses包住
- 对于@ApiImplicitParam的paramType:query、form域中的值需要使用@RequestParam获取, header域中的值需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name就不能是body,否则有问题,与官方文档中的“If paramType is "body", the name should be "body"不符。
完整demo下载地址:https://github.com/jlq023/spring_swaggerDemo
springMvc+swagger整合例子的更多相关文章
- Swagger UI 与SpringMVC的整合 II
pom.xml <!-- swagger开始 --> <dependency> <groupId>io.springfox</groupId> < ...
- Swagger UI 与SpringMVC的整合
关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API. S ...
- Swagger与SpringMVC项目整合
Swagger与SpringMVC项目整合 来源:http://www.2cto.com/kf/201502/376959.html 为了方便的管理项目中API接口,在网上找了好多关于API接口管理的 ...
- 【SpringMVC学习04】Spring、MyBatis和SpringMVC的整合
前两篇springmvc的文章中都没有和mybatis整合,都是使用静态数据来模拟的,但是springmvc开发不可能不整合mybatis,另外mybatis和spring的整合我之前学习mybati ...
- Spring+springmvc+Mybatis整合案例 annotation版(myeclipse)详细版
Spring+springmvc+Mybatis整合案例 Version:annotation版 文档结构图: 从底层开始做起: 01.配置web.xml文件 <?xml version=&qu ...
- Spring+springmvc+Mybatis整合案例 xml配置版(myeclipse)详细版
Spring+springmvc+Mybatis整合案例 Version:xml版(myeclipse) 文档结构图: 从底层开始做起: 01.配置web.xml文件 <?xml version ...
- Jbpm4.4+hibernate3.5.4+spring3.0.4+struts2.1.8整合例子(附完整的请假流程例子,jbpm基础,常见问题解决)
Jbpm4.4+hibernate3.5.4+spring3.0.4+struts2.1.8 整合例子(附完整的请假流程例子). 1.jbpm4.4 测试环境搭建 2.Jbpm4.4+hibernat ...
- SpringMVC+redis整合
在网络上有一个很多人转载的springmvc+redis整合的案例,不过一直不完整,也是被各种人装来转去,现在基本将该框架搭建起来. package com.pudp.bae.base; import ...
- sonne_game网站开发03 spring-mvc+freemarker整合
今天的任务就是在spring+mybatis+springmvc的基础上,将freemarker整合进来. freemarker是什么? freemarker是一种模板引擎.它的目的是基于模板和数据, ...
随机推荐
- [国嵌攻略][048][MMU配置与使用]
MMU配置与使用 1.通过点亮LED使用虚拟地址来使用MMU,采用段页映射方式 2.任务步骤:1.建立一级页表 2.写入TTB 3.打开MMU 代码编写 1.虚拟地址的段地址0xA0000000,一级 ...
- 免费V P N获取方式。
给需要加速器链接国外网站的朋友, 打开网址:http://miaoaff.com/reg.php?id=204250: 用一个邮箱注册,就会得到一个免费的vpn软件账号(包含300M流量时间永久): ...
- POJ 3790 最短路径问题(Dijkstra变形——最短路径双重最小权值)
题目链接: http://acm.hdu.edu.cn/showproblem.php?pid=3790 Problem Description 给你n个点,m条无向边,每条边都有长度d和花费p,给你 ...
- 【JSP/Servlet】后台如何获取复选框或可选属性的同名参数
感觉自己jsp/servlet部分学的太差了--今天突然想到还有这种操作,遂分享之 比如有些时候我们需要使用复选框发送同名数据的时候,后台接收参数是个麻烦事,还有可选属性也是如此 有丰富经验的会想到a ...
- wamp配置虚拟机步骤
1.首先修改C:\Windows\System32\drivers\etc下的hosts文件 添加一行 127.0.0.1 myblog.org //映射到本机 2.然后修 ...
- Android + Eclipse + PhoneGap 环境配置
用了3天的时间,终于把环境搭建完毕,郁闷了N天,终于完成了.这里我只是讲述我安装的过程,仅供大家参考. 环境搭建首先要去下载一些安装包: (下载前注意一下,电脑是32位还是64位的请注意选择安装包) ...
- PowerShell 异常处理
在使用 PowerShell 的过程中,发现它的异常处理并不像想象中的那么直观,所以在这里总结一下. Terminating Errors 通过 ThrowTerminatingError 触发的错误 ...
- 04 整合IDEA+Maven+SSM框架的高并发的商品秒杀项目之高并发优化
Github:https://github.com/nnngu 项目源代码:https://github.com/nnngu/nguSeckill 关于并发 并发性上不去是因为当多个线程同时访问一行数 ...
- shell 学习四十五天---xargs
当 find 产生一个文件列表时,该列表提供给另一个命令有时是很有用的.案例: $touch abc.c erd.c oiy.c $ll ./erd.c ./abc.c ./oiy.c $find - ...
- Django_注册全局消息
需求: 对于登录用户,无论他在哪个页面,我都需要给他全局发送一个消息提示,Django中request就是一个全局变量 那,如何做? 在models 中urser表,继承user的表类中写上一个函数, ...