4.7 Spring Boot整合Swagger2，搭建Restful API在线文档
Swagger，中文“拽”的意思，它是一个功能强大的在线API文档的框架，目前它的版本为2.x，所以称为Swagger2。Swagger2提供了在线文档的查阅和测试功能。利用Swagger2很容易构建RESTful风格的API，在Spring Boot中集成Swagger2，在本案例中需要以下5个步骤。
（1）引入依赖
在工程的pom文件中引入依赖，包括springfox-swagger2和springfox-swagger-ui的依赖，代码如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
（2）配置Swagger2
写一个配置类Swagger2，在类的上方加上@Configuration注解，表明是一个配置类，加上@EnableSwagger2开启Swagger2的功能。在配置类Swagger2中需要注入一个Docket的Bean，该Bean包含了apiInfo，即基本API文档的描述信息，以及包扫描的基本包名等信息，代码如下：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.forezp.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restful风格，http://blog.csdn.net/forezp")
.termsOfServiceUrl("http://blog.csdn.net/forezp")
.version("1.0")
.build();
}
}
（3）写生成文档的注解
Swagger2通过注解来生成API接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档，以下的注解能够满足基本需求，注解及其描述如下。
•@Api：修饰整个类，用于描述Controller类。
•@ApiOperation：描述类的方法，或者说一个接口。
•@ApiParam：单个参数描述。
•@ApiModel：用对象来接收参数。
•@ApiProperty：用对象接收参数时，描述对象的一个字段。
•@ApiResponse：HTTP响应的一个描述。
•@ApiResponses：HTTP响应的整体描述。
•@ApiIgnore：使用该注解，表示Swagger2忽略这个API。
•@ApiError：发生错误返回的信息。
•@ApiParamImplicit：一个请求参数。
•@ApiParamsImplicit：多个请求参数。
（4）编写Service层代码
本节案例在4.5节的案例基础之上进行改造，构建了一组RESTful风格的API接口，包括获取User列表、创建User、修改User、根据用户名获取User、删除User的API接口，对应于Service层的代码如下：
@Service
public class UserService {
@Autowired
private UserDao userRepository;
public User findUserByName(String username){
return userRepository.findByUsername(username);
}
public List<User> findAll(){
return userRepository.findAll();
}
public User saveUser(User user){
return userRepository.save(user);
}
public User findUserById(long id){
return userRepository.findOne(id);
}
public User updateUser(User user){
return userRepository.saveAndFlush(user);
}
public void deleteUser(long id){
userRepository.delete(id);
}
}
（5）Web层
在Web层通过Get、Post、Delete、Put这4种Http方法，构建一组以资源为中心的RESTful风格的API接口，代码如下：
@RequestMapping("/user")
@RestController
public class UserController {
@Autowired
UserService userService;
@ApiOperation(value="用户列表", notes="用户列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<User> getUsers() {
List<User> users = userService.findAll();
return users;
}
@ApiOperation(value="创建用户", notes="创建用户")
@RequestMapping(value="", method=RequestMethod.POST)
public User postUser(@RequestBody User user) {
return userService.saveUser(user);
}
@ApiOperation(value="获用户细信息", notes="根据url的id来获取详细信息")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return userService.findUserById(id);
}
@ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
@RequestMapping(value="/{id}", method= RequestMethod.PUT)
public User putUser(@PathVariable Long id, @RequestBody User user) {
User user1 = new User();
user1.setUsername(user.getUsername());
user1.setPassword(user.getPassword());
user1.setId(id);
return userService.updateUser(user1);
}
@ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
userService.deleteUser(id);
return "success";
}
@ApiIgnore//使用该注解忽略这个API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}
通过@ApiOperation注解描述生成在线文档的具体API的说明，其中value值为该接口的名称，notes值为该接口的详细文档说明。这样就可以让Swagger2生成在线的API接口文档了。如果不需要某接口生成文档，只需要再加@ApiIgnore注解即可。启动工程，在浏览器上访问http://localhost:8080/swagger-ui.html，浏览器显示Swagger-UI在线文档的界面，界面如图4-2所示。
▲图4-2 Swagger-UI在线文档的界面