Spring Cloud与微服务构建（四）开发框架Spring Boot 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-wagger-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.rock.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.youkuaiyun.com/rock")
                .termsOfServiceUrl("https://blog.youkuaiyun.com/qq_40929047")
                .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 userDao;
    public User findUserByName(String username){
        return userDao.findByUsername(username);
    }
    public List<User>findAll(){
        return userDao.findAll();
    }
    public User savaUser(User user){
        return userDao.save(user);
    }
    public User findUserById(long id){
        return userDao.findOne(id);
    }
    public User updateUser(User user){
        return userDao.saveAndFlush(user);
    }
    public void deleteUser(long id){
        userDao.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(){
        return userService.findAll();
    }
    @ApiOperation(value = "创建用户",notes = "创建用户")
    @RequestMapping(value = "",method = RequestMethod.POST)
    public User postUser(@RequestBody User user){
        return userService.savaUser(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在线文档的界面，界面如图