转载自:http://www.360doc.com/content/17/0914/17/16915_687184334.shtml
实际项目中非常需要写文档,提高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关键配置 [html] view plain copy
- <dependency>
- <groupId>com.mangofactory</groupId>
- <artifactId>swagger-springmvc</artifactId>
- <version>1.0.2</version>
- </dependency>
-
- <dependency>
- <groupId>org.springframework</groupId>
- <artifactId>spring-webmvc</artifactId>
- <version>4.1.6.RELEASE</version>
- </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: [java] view plain copy
- @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "list", method = RequestMethod.POST)
- public Result<User> list(
- @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
- @ApiParam(value = "token", required = true) @RequestParam String token) {
- Result<User> result = new Result<User>();
- User user = new User();
- result.setData(user);
- return result;
- }
@ApiParam(value = "token", required = true) @RequestParam String token Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。 例子2: [java] view plain copy
- @ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
- @ResponseBody
- @RequestMapping(value = "update", method = RequestMethod.GET/*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
- public Result<String> 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: [java] view plain copy
- public Result<String> 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,不通用,局限性比较大。 五、若干截图 六、源代码 [java] view plain copy
- 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;
-
- /**
- * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
- * 博客:http://blog.csdn.net/fansunion
- *
- */
- @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<User> 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<User> result = new Result<User>();
- 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)
- // @RequestBody只能有1个
- // 使用了@RequestBody,不能在拦截器中,获得流中的数据,再json转换,拦截器中,也不清楚数据的类型,无法转换成java对象
- // 只能手动调用方法
- public Result<String> 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<String> update(User user) {
- String u = findUser(user);
- System.out.println(u);
- return null;
- }
-
- private String findUser(User user) {
- String token = user.getToken();
- return token;
- }
- }
[java] view plain copy
- package cn.fansunion.swagger.serverapi.controller;
-
- import com.wordnik.swagger.annotations.ApiModel;
- import com.wordnik.swagger.annotations.ApiModelProperty;
-
- /**
- * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
- * 博客:http://blog.csdn.net/fansunion
- *
- */
- @ApiModel(value = "用户对象", description = "user2")
- public class User extends CommonParam {
-
- @ApiModelProperty(value = "商品信息", required = true)
- private String name;
- @ApiModelProperty(value = "密码", required = true)
- private String password;
-
- @ApiModelProperty(value = "性别")
- private Integer sex;
- @ApiModelProperty(value = "密码", required = true)
- private String token;
-
- public String getToken() {
- return token;
- }
-
- public void setToken(String token) {
- this.token = token;
- }
-
- public String getName() {
- return name;
- }
-
- public void setName(String name) {
- this.name = name;
- }
-
- public String getPassword() {
- return password;
- }
-
- public void setPassword(String password) {
- this.password = password;
- }
-
- public Integer getSex() {
- return sex;
- }
-
- public void setSex(Integer sex) {
- this.sex = sex;
- }
-
- }
[java] view plain copy
- package cn.fansunion.swagger.serverapi.swagger;
-
- import org.springframework.beans.factory.annotation.Autowired;
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.Configuration;
- import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
- import org.springframework.web.servlet.config.annotation.EnableWebMvc;
- import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
-
- import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
- import com.mangofactory.swagger.models.dto.ApiInfo;
- import com.mangofactory.swagger.paths.SwaggerPathProvider;
- import com.mangofactory.swagger.plugin.EnableSwagger;
- import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
-
- @Configuration
- @EnableWebMvc
- @EnableSwagger
- public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
-
- private SpringSwaggerConfig springSwaggerConfig;
-
- @Autowired
- public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
- this.springSwaggerConfig = springSwaggerConfig;
- }
-
- /**
- * 链式编程 来定制API样式 后续会加上分组信息
- *
- * @return
- */
- @Bean
- public SwaggerSpringMvcPlugin customImplementation() {
- return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
- .apiInfo(apiInfo()).includePatterns(".*")
- .useDefaultResponseMessages(false)
- // .pathProvider(new GtPaths())
- .apiVersion("0.1").swaggerGroup("user");
-
- }
-
- private ApiInfo apiInfo() {
- ApiInfo apiInfo = new ApiInfo("小雷移动端API接口平台",
- "提供详细的后台所有Restful接口", "http://blog.csdn.net/FansUnion",
- "[email protected]", "小雷博客", "http://blog.csdn.net/FansUnion");
- return apiInfo;
- }
-
- @Override
- public void configureDefaultServletHandling(
- DefaultServletHandlerConfigurer configurer) {
- configurer.enable();
- }
-
- class GtPaths extends SwaggerPathProvider {
-
- @Override
- protected String applicationPath() {
- return "/restapi";
- }
-
- @Override
- protected String getDocumentationPath() {
- return "/restapi";
- }
- }
-
- }
|