springMvc+swagger整合例子
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”不符。