Swagger与SpringMVC项目整合

最新推荐文章于 2019-04-15 20:46:29 发布

weixin_34417635

最新推荐文章于 2019-04-15 20:46:29 发布

阅读量120

点赞数

文章标签： java ui 测试

原文链接：https://my.oschina.net/hapier/blog/786430

版权

为什么80%的码农都做不了架构师？>>>

Swagger简介： Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

加上最近公司在培训了一次Swagger,个人觉得非常不错，并且一直在寻找接口文档规范的框架.接下来让我们一起来学习如何使用Swagger来生成接口文档吧！

前置条件：你已经使用SpringMVC搭建了一套接口服务

一.项目中引入相关依赖

<!-- swagger-springmvc -->
		<dependency>
			<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>

二.自定义SwaggerConfig类

Swagger的配置实际上就是自定义一个Config类，通过java编码的方式实现配置。代码如下：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

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;

@Configuration
@EnableSwagger
public class SwaggerConfig {

	@Autowired
	private SpringSwaggerConfig springSwaggerConfig;

	@Bean
	public SwaggerSpringMvcPlugin customImplementation() {
		return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");
	}

	private ApiInfo apiInfo() {
		ApiInfo apiInfo = new ApiInfo(
				"My Apps API Title", 
				"My Apps API Description", 
				"My Apps API terms of service", 
				"My Apps API Contact Email", 
				"My Apps API Licence Type", 
				"My Apps API License URL");
		return apiInfo;
	}
}

三.将此配置加入到SpringMVC配置文件中，如下：

<bean class="com.qk365.api.SwaggerConfig" />

四.定义接口测试类、方法

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import com.qk365.entity.User;
import com.qk365.exception.BusinessException;
import com.qk365.service.UserService;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;

@Controller
@RequestMapping("/user")
public class UserController {

	@Autowired
	private UserService userService;

	/**
	 * 根据用户名获取用户对象
	 */
	@RequestMapping(value = "/getUserByUserName/{name}", method = RequestMethod.GET)
	@ResponseBody
	@ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")
	public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception {
		User user = userService.getUserByUserName(name);
		if (user != null) {
			ApiResult result = new ApiResult();
			result.setCode(0);
			result.setMessage("success");
			result.setData(user);
			return result;
		} else {
			throw new BusinessException("根据{name=" + name + "}获取不到User对象");
		}
	}
}