1、需求背景

SpringMVC本身就可以开发出基于rest风格的服务,通过简单的配置,即可快速开发出一个可供客户端调用的rest服务,通常这些服务要不就是用于手机app的开发,要不就是提供给第三方开发者使用,不管哪种情况,你都需要提供详细的说明给别人,而Swagger就是为这种情况而生的,通过在接口上的注解,生成可供第三方模拟测试和阅读的接口列表,既美观又使用,真是行走江湖之必备良药。
下面先上美图:

好了,下面言归正传,该如何将Swagger集成到springMVC中呢?

2、依赖包以及Swagger-ui版本

  • 如果你用的是maven,依赖包如下:
    <groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<!-- swagger-springmvc dependencies -->
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
  • 如果你用的是jeesite框架的话,你只需引入下面三个lib即可:
swagger-annotations-1.3.11.jar
swagger-models-1.0.2.jar
swagger-springmvc-1.0.2.jar
  • Swagger-ui版本

大家可以到https://github.com/swagger-api/swagger-ui/releases下载最新的版本,目前最新版本为2.1.4

3、新建配置Java文件

在你的JavaWeb工程中新建一个名为SwaggerConfig的java文件,代码如下:

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.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; /**
* @author xiegx
* @version 创建时间:2016-8-16 下午2:01:10
* SwaggerUI配置
*/
@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan(basePackages ={"com.xxx.soa"})
public class SwaggerConfig extends WebMvcConfigurerAdapter { private SpringSwaggerConfig springSwaggerConfig; /**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
} /**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*")
.swaggerGroup("XmPlatform")
.apiVersion("1.0.0");
} @Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
/*
* "标题 title",
* "描述 description",
* "termsOfServiceUrl",
* "联系邮箱 contact email",
* "许可证的类型 license type",
* "许可证的链接 license url"
*/
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"xxx平台API文档",
"后台RESTful API",
"",//
"admin@xmplatform.com",
"",
"");
return apiInfo;
}
}

注意:basePackages为扫描的包路径(你的controller所在的包路径),其他的东西大家看看应该就懂的了,就不多说了。

4、新建测试Controller

例如新建一个TestController.java,代码如下:

@Controller
@RequestMapping(value = "/soa/test")
@Api(value="TestController",description="测试接口描述")
public class TestController {
/*
* @ApiOperation(value = "接口说明", httpMethod ="接口请求方式", response ="接口返回参数类型", notes ="接口发布说明"
*
* @ApiParam(required = "是否必须参数", name ="参数名称", value ="参数具体描述"
*/
@RequestMapping(value = {""})
@ApiOperation(value="接口说明(测试)",httpMethod="GET",notes="在没有会话、没有签名的情况下,进入方法体")
public void test(HttpServletRequest request, HttpServletResponse response, Model model) {
try {
response.getWriter().write("ignoreAll");
} catch (IOException e) {
e.printStackTrace();
}
}
}

上述代码中的几个注解需要说明一下:

  • Api 表明可供Swagger展示的接口类,value表示接口类的描述(Controller类的这个注解可加可不加,加这个注解更多的是为了显示接口类的描述)
  • ApiOperation 表明这个方法供Swagger展示的接口方法,value等含义详细可看上述代码中的注释
  • ApiParam 方法中的参数只有加了这个注解,才能显示中文描述,否则只显示英文

5、静态资源文件的配置

将步骤2、中提到的最新版本的Swagger-ui拷贝到你的JavaWeb工程中

假如你用的是jeesite框架,你可以拷贝到static目录下,例如static\swagger;你也可以拷贝到WEB-INF目录下,例如WEB-INF\swagger,不过此时你需要在springMVC配置文件中进行静态文件过滤的处理,例如<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

6、收工,启动应用服务器

打开浏览器,访问swagger目录中的index.html,即可看到美观的接口文档呈现在你面前。

You Want More ?Ok,That is it

1、如何汉化/显示中文

swagger-ui本身是支持多语言的,在index.html中有这么一段代码:

<!-- Some basic translations -->
<!-- <script src='lang/translator.js' type='text/javascript'></script> -->
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<!-- <script src='lang/en.js' type='text/javascript'></script> -->

大家只需要把注释打开,同时加入对应的中文js即可,最终修改如下:

<!-- Some basic translations -->
<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>
<!-- <script src='lang/en.js' type='text/javascript'></script> -->

2、在swagger-ui中默认的参数的Content Type是application/json,测试时发现后台参数没有接收到值,怎么办?

大家可能会问,Content Type是application/json有什么影响,为什么要修改为其他呢?这里就要涉及到springMVC中将请求传递过来的参数注入到Controller方法对应对象的原理了,具体知识大家可以搜索一下,这个不是本文重点我就不多讲了,其实我们通常写的Controller方法,默认的Content Type其实是application/x-www-form-urlencoded,而swagger中参数的默认Content Type是application/json,这样就会导致使用swagger测试时,提交到Controller方法的对应参数无法正确注入。

  • 那么,该如何处理呢,能改成其他吗?

其实在swagger-ui的Issues中有人提到过,https://github.com/swagger-api/swagger-ui/issues/658,解决的办法就是要设置consumes这个东东。

  • 解决办法找到了,那consumes在哪里设置呢?

答案就是在@ApiOperation这个注解里面进行设置,将consumes修改为“application/x-www-form-urlencoded”即可,例如:

@ApiOperation(value="接口说明(测试)",httpMethod="GET",consumes="application/x-www-form-urlencoded",notes="在没有会话、没有签名的情况下,进入方法体")

  • 那在什么情况下,参数的Content Type才是application/json呢?

当你的参数加了@RequestBody注解的时候,表示此参数接收的是json数据,这个时候你就可以将consumes写为application/json了

3、想要知道ApiOperation注解中httpMethod等参数都能写哪些值?

这个看api文档吧,提供一个地址给大家:http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html

基于SpringMVC下的Rest服务框架搭建【集成Swagger】的更多相关文章

  1. 基于SpringMVC下的Rest服务框架搭建【1、集成Swagger】

    基于SpringMVC下的Rest服务框架搭建[1.集成Swagger] 1.需求背景 SpringMVC本身就可以开发出基于rest风格的服务,通过简单的配置,即可快速开发出一个可供客户端调用的re ...

  2. 基于全注解的SpringMVC+Spring4.2+hibernate4.3框架搭建

    概述 从0到1教你搭建spring+springMVC+hibernate整合框架,基于注解. 本教程框架为基于全注解的SpringMVC+Spring4.2+hibernate4.3,开发工具为my ...

  3. SprngCloud微服务框架搭建(一)

    参照来源 :https://blog.csdn.net/forezp/article/details/70148833 1.简介 目前来说,SpringCloud是比较完整的微服务解决方案框架.不像其 ...

  4. 基于LDAP下的Samba服务

    基于LDAP下的Samba服务 一.环境情况: 实验环境:俩台机器,分别为2012R2,安装有 AD 并作为域控制器Domain Controller(DC),同时也作为 DNS 服务器和时间服务器: ...

  5. [Visual Studio] SOA服务框架搭建

    1.服务框架搭建 2.服务模板创建 3.Nuget引用 4.客户端调用 任务点: 1.分析SOA 2.修改SOA架构名称以及关键字 3.使用Nuget添加引用 4.选择服务模板进行创建 5.尝试调用 ...

  6. redis在Windows下以后台服务一键搭建哨兵(主从复制)模式(多机)

    redis在Windows下以后台服务一键搭建哨兵(主从复制)模式(多机) 一.概述 此教程介绍如何在windows系统中多个服务器之间,布置redis哨兵模式(主从复制),同时要以后台服务的模式运行 ...

  7. redis在Windows下以后台服务一键搭建哨兵(主从复制)模式(单机)

    redis在Windows下以后台服务一键搭建哨兵(主从复制)模式(单机) 一.概述 此教程介绍如何在windows系统中单机布置redis哨兵模式(主从复制),同时要以后台服务的模式运行.布置以脚本 ...

  8. redis在Windows下以后台服务一键搭建集群(多机器)

    redis在Windows下以后台服务一键搭建集群(多机器) 一.概述 此教程介绍如何在windows系统中多台机器之间布置redis集群,同时要以后台服务的模式运行.布置以脚本的形式,一键完成.多台 ...

  9. redis在Windows下以后台服务一键搭建集群(单机--伪集群)

    redis在Windows下以后台服务一键搭建集群(单机--伪集群) 一.概述 此教程介绍如何在windows系统中同一台机器上布置redis伪集群,同时要以后台服务的模式运行.布置以脚本的形式,一键 ...

随机推荐

  1. (40) Aeroo 服务安装

    服务器 Odoo 8.0 操作系统: Ubuntu trusty14.04 说明:安装aeroo 要的要两个服务 areoo-docs 和 soffice 这里设定两个端口 8989 和 8100 = ...

  2. JavaScript的Date对象

    整理了一些JavaScript时间的对象,如下所示: toLocaleString()得到当前的年月日和时间的字符串 toLocaleTimeString() 得到当前的时间字符串 toLocaleD ...

  3. C#获取参数getParameter

    昨天遇到了这样一个问题,getParameter时,首次进入页面读取默认值时,本应该读取到“全部”这个字符. 然后在实际读取过程当中却不是这样,实际读取到的是  类的对象值 重新运行时能够读取到 “全 ...

  4. jquery ajax跨域请求webservice webconfig配置

    <configuration> <system.web> <compilation debug="true" targetFramework=&quo ...

  5. 使用 CSS 媒体查询创建响应式网站

    简介 现今每天都有更多的手机和平板电脑问市.消费者能够拥有可想象到的各种规格和形状的设备,但是网站开发人员却面临一个挑战:如何使他们的网站在传统浏览器.手机和平板电脑浏览器上有很好的效果,如何在各种大 ...

  6. enmo_day_08

    性能监视 管理内存组件 自动内存管理(AMM) : 指定分配给实例的总内存(SGA, PGA) 自动共享内存管理(ASMM) : 指定SGA, 管理分配给共享池, java池, 动态性能视图 :v$( ...

  7. spring-mvc xml文件的最基本配置

    <?xml version="1.0" encoding="UTF-8"?><beans xmlns="http://www.spr ...

  8. SQLite简单使用说明

    System.Data.SQLite.dll下载地址 http://system.data.sqlite.org/index.html/doc/trunk/www/downloads.wiki 选择. ...

  9. POI XSSF与HSSF的 使用区别

    首次写博客,希望能坚持下去,一点一滴的积累,内容不多也不深,但愿我的分享,能帮助和我一样的新人们解决问题 最近给项目中添加了一个导入excel表格的功能,然而在功能开发结束后测试,发现报错. 报错信息 ...

  10. 探索javascript----获得节点计算后样式

    节点计算后样式是一个属性与属性值的值对对象: IE:    node.currentStyle; 非IE: window.getComputedStyle(node,null); 兼容方式: func ...