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对象");
}
}
}
相关说明:
其中@ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下:
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”;其他参数可参考源码;
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”
五.添加Swagger UI配置
从https://github.com/swagger-api/swagger-ui 下载获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp目录下,如图所示:
六.修改上图标注红色的index.html文件中url值
将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json修改为:
http://localhost:8080/{projectname}/api-docs
七.启动项目, 访问查看是否整合成功
到此为止,所有配置完成,启动你的项目,访问http://localhost:8080/{projectName}/
可看到如下所示页面表示你已经整合成功!
项目源码:链接:http://pan.baidu.com/s/1bXvrS6 密码:d5q7
启动方式:可用tomcat 插件启动,启动命令:clean tomcat7:run