Swagger是一个用于描述和测试restful接口的工具，只要在定义restful接口时增加一些类和方法的描述注解，通过很简单的配置就可以得到一个展示接口定义的页面，也可以在页面上设置参数提交测试接口(替代postman的部分功能)。
接口修改后不需要单独修改描述文档，swagger自动生成接口文档。下面讲一下如果搭建一个最简单swagger测试Demo。
一、创建一个SpringBoot的maven项目
项目创建方式可以参考我这篇博客《Spring Boot初探之restful服务发布》，项目创建后的目录如下：
二、创建好后在pom.xml文件中增加swagger依赖的包
1 <dependency> 2 3 <groupId>io.springfox</groupId> 4 5 <artifactId>springfox-swagger2</artifactId> 6 7 <version>2.8.0</version> 8 9 </dependency> 10 11 <dependency> 12 13 <groupId>io.springfox</groupId> 14 15 <artifactId>springfox-swagger-ui</artifactId> 16 17 <version>2.8.0</version> 18 19 </dependency>
直接使用appache的仓库：
1 <repository> 2 <id>springfox-swagger</id> 3 <url>https://mvnrepository.com/artifact/io.springfox/springfox-swagger2</url> 4 </repository> 5 <repository> 6 <id>springfox-swagger-ui</id> 7 <url>https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui</url> 8 </repository>
三、添加swagger的配置加载类(Swagger2Config.java)
1 package com.elon.springbootdemo.config; 2 3 import org.springframework.context.annotation.Bean; 4 import org.springframework.context.annotation.Configuration; 5 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; 6 7 import springfox.documentation.builders.ApiInfoBuilder; 8 import springfox.documentation.builders.PathSelectors; 9 import springfox.documentation.builders.RequestHandlerSelectors; 10 import springfox.documentation.service.ApiInfo; 11 import springfox.documentation.spi.DocumentationType; 12 import springfox.documentation.spring.web.plugins.Docket; 13 import springfox.documentation.swagger2.annotations.EnableSwagger2; 14 15 @Configuration 16 @EnableSwagger2 17 public class Swagger2Config extends WebMvcConfigurerAdapter { 18 @Bean 19 public Docket api() { 20 return new Docket(DocumentationType.SWAGGER_2) 21 .select() 22 .apis(RequestHandlerSelectors.basePackage("com.elon.springbootdemo.ws")) 23 .paths(PathSelectors.any()) 24 .build() 25 .apiInfo(getApiInfo()); 26 } 27 28 private ApiInfo getApiInfo() 29 { 30 ApiInfo apiInfo = new ApiInfoBuilder().title("用户管理模块") 31 .description("定义用户数据的增加、删除、修改接口") 32 .termsOfServiceUrl("http://www.cnblogs.com/elon") 33 .version("1.0") 34 .build(); 35 return apiInfo; 36 } 37 }
四、添加用于测试的restful接口(WSUserSwagger.java)
1 package com.elon.springbootdemo.ws; 2 3 import org.springframework.web.bind.annotation.PathVariable; 4 import org.springframework.web.bind.annotation.RequestBody; 5 import org.springframework.web.bind.annotation.RequestHeader; 6 import org.springframework.web.bind.annotation.RequestMapping; 7 import org.springframework.web.bind.annotation.RequestMethod; 8 import org.springframework.web.bind.annotation.RequestParam; 9 import org.springframework.web.bind.annotation.RestController; 10 11 import io.swagger.annotations.Api; 12 import io.swagger.annotations.ApiOperation; 13 14 @RestController 15 @RequestMapping(value="swagger-demo") 16 @Api(value="WSUserSwagger", description="用户信息管理") 17 public class WSUserSwagger { 18 19 @ApiOperation(value="添加用户", notes="添加用户") 20 @RequestMapping(value="/v1/user", method=RequestMethod.POST) 21 public String addUser(@RequestBody String userInfo) { 22 return "Add user:" + userInfo; 23 } 24 25 @ApiOperation(value = "根据名称查询用户", notes = "根据名称查询用户") 26 @RequestMapping(value = "/v1/user", method = RequestMethod.GET) 27 public String queryUserByName(@RequestParam("name") String name, @RequestHeader("age") int age) { 28 return name + age; 29 } 30 31 @ApiOperation(value="删除用户", notes="删除用户") 32 @RequestMapping(value="/v1/user/{name}", method=RequestMethod.DELETE) 33 public String deleteUser(@PathVariable("name") String name) { 34 return "delete " + name; 35 } 36 }
五、启动后测试
在浏览器中输入 http://localhost:8080/swagger-ui.html。打开页面可以看到定义的接口：
测试GET方法：点”Try it out”后输入参数， 点击”execute”执行可以看到接口执行后的返回结果。
