Swagger与SpringMVC项目整合

来源：互联网发布：java 国家精品课程编辑：程序博客网时间：2024/05/17 10:28

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@EnableSwaggerpublic class SwaggerConfig {@Autowiredprivate SpringSwaggerConfig springSwaggerConfig;@Beanpublic 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 {@Autowiredprivate 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对象");}}}