实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。
听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。
一:Swagger介绍
Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目
实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,
同时swagger-ui还可以测试spring restful风格的接口功能。
官方网站为:http://swagger.io/
中文网站:http://www.sosoapi.com
二:Swagger与Spring MVC集成步骤
1.Maven关键配置
- <dependency>
- <groupId>com.mangofactorygroupId>
- <artifactId>swagger-springmvcartifactId>
- <version>1.0.2version>
- dependency>
-
- <dependency>
- <groupId>org.springframeworkgroupId>
- <artifactId>spring-webmvcartifactId>
- <version>4.1.6.RELEASEversion>
- dependency>
2. 插件配置
CustomJavaPluginConfig
3.复制swagger的相关js等静态资源到webapp目录。
swagger-ui.js之类的。
我copy过一次,但是有问题,最后从网上下载了一个项目,可以直接用的那种。
然后自己再逐步改造。
4.启动项目
http://localhost:8080/
三、常见swagger注解一览与使用
最常用的5个注解
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
其它若干
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
四、关键代码和实际例子
例子1:
- @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "list", method = RequestMethod.POST)
- public Result list(
- @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
- @ApiParam(value = "token", required = true) @RequestParam String token) {
- Result result = new Result();
- User user = new User();
- result.setData(user);
- return result;
- }
@ApiParam(value = "token", required = true) @RequestParam String token
Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。
例子2:
- @ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "update", method = RequestMethod.GET)
- public Result update(User user) {
- String u = findUser(user);
- System.out.println(u);
- return null;
- }
当参数太多的时候,需要定义太多的参数,排版看起来很不舒服。
这个时候,可以使用对象来接收。
@ApiModel(value = "用户对象",description="user2")
public class User extends CommonParam{
}
Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。
这里面存在一个小问题,当后端用对象User来接收参数的时候,Swagger自带的工具是这样的:
这种形式,并不是表单提交,或者把参数附加到URL的后面。
我们只能手动构造URL,附带参数去提交。
如果需要测试的话!
例子3:
- public Result add(@RequestBody User user) {
- String u = findUser(user);
- System.out.println(u);
- return null;
- }
Web前端/移动端HTTP请求方式:必须把参数,放到request请求的body中去。
后端不能直接用request.getParam("token")这种。
获得request body中的数据,手动转换成目标数据。
String charReader(HttpServletRequest request) throws IOException {
BufferedReader br = request.getReader();
String str, wholeStr = "";
while ((str = br.readLine()) != null) {
wholeStr += str;
}
return wholeStr;
}
个人推荐:
1.参数不多的时候,用例子1,用@ApiParam注解生成文档。
swagger可视化界面,可以直接设置参数,发送请求来测试
2.参数比较多的时候,用例子2,用对象来接收参数,在对象里针对每个字段,@ApiModelProperty注解生成文档。
swagger可视化界面,可以直接设置参数,但是无法接收到。
因此,推荐使用其它HTTP请求或POST模拟工具,发送请求,模拟测试。
不推荐例子3,不通用,局限性比较大。
五、若干截图
六、源代码
- package cn.fansunion.swagger.serverapi.controller;
-
- import org.springframework.http.MediaType;
- import org.springframework.stereotype.Controller;
- import org.springframework.web.bind.annotation.RequestBody;
- import org.springframework.web.bind.annotation.RequestMapping;
- import org.springframework.web.bind.annotation.RequestMethod;
- import org.springframework.web.bind.annotation.RequestParam;
- import org.springframework.web.bind.annotation.ResponseBody;
-
- import com.wordnik.swagger.annotations.Api;
- import com.wordnik.swagger.annotations.ApiOperation;
- import com.wordnik.swagger.annotations.ApiParam;
-
-
-
-
-
-
- @Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
- @Controller
- @RequestMapping("user")
- public class UserController {
-
-
- @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "list", method = RequestMethod.POST)
- public Result list(
- @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
- @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
- @ApiParam(value = "token", required = true) @RequestParam String token) {
- Result result = new Result();
- User user = new User();
- result.setData(user);
- return result;
- }
-
- @ApiOperation(value = "添加用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "add", method = RequestMethod.POST)
-
-
-
- public Result add(@RequestBody User user) {
- String u = findUser(user);
- System.out.println(u);
- return null;
- }
-
- @ApiOperation(value = "update用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "update", method = RequestMethod.GET)
- public Result update(User user) {
- String u = findUser(user);
- System.out.println(u);
- return null;
- }
-
- private String findUser(User user) {
- String token = user.getToken();
- return token;
- }
- }
七、项目下载地址
http://git.oschina.net/fansunion/swagger-server-api/tree/master/
八、参考资料
http://blog.csdn.net/jia20003/article/details/50700736
http://www.cnblogs.com/quanyongan/archive/2013/04/16/3024741.html
http://www.cnblogs.com/h9527/p/5506956.html
http://www.cnblogs.com/yuananyun/p/4993426.html