SpringBoot + Springfox RESTful API（下篇）- 构建 Swagger API文档

 

上篇我们讲了如何和利用MockMvc来测试我们的RESTfulAPI，没看过的请移步：（https://my.oschina.net/codingcloud/blog/1588662），但MockMvc需要编写大量的测试代码，在很多的快速迭代的项目中并不是那么适用。所以这篇我们会学习一个更便捷的API工具：Swagger

什么是Swagger?

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发

Swagger官网快速入口：https://swagger.io

 

如何将Swagger和SpringBoot整合？

一、引入swagger依赖jar包的maven配置

			io.springfox
			springfox-swagger2
			2.2.2
		
		
			io.springfox
			springfox-swagger-ui
			2.2.2
		

二、编写java代码

1、编写SwaggerConfigruation.java 这类来负责管理swagger的参数配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 *
 * Swagger2 配置类
 *
 * 

 *     @Configuration 让spring加载该类配置
 *     @EnableSwagger2 启用swagger2
 * 
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("文档中心")
                .termsOfServiceUrl("https://my.oschina.net/codingcloud/blog")
                .contact("codingcloud")
                .license("北京xxx有限公司")
                .version("1.0")
                .description("备注信息")
                .build();
    }
}

2、创建一个UserController.java 我们编写的api接口

只需要关注几个注解即可， @ApiOperation 和 @ApiImplicitParam

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/**
 * 构建restful API文档
 * Created by nasheng.yun on 2017/12/12.
 */
@SuppressWarnings("Duplicates")
@RestController
@RequestMapping(value = "user")
public class UserController {

    // 创建线程安全的map
    static Map users = new ConcurrentHashMap<>();

    @ApiOperation(value = "获取用户列表",notes = "xxx")
    @GetMapping(value = "getUserList")
    public List list(){
        List userList = new ArrayList<>(users.values());

        System.out.println("UserController.list");
        return userList;
    }

    @ApiOperation(value = " 创建用户",notes = "根据User对象来创建用户")
    @ApiImplicitParam(name = "user",value = "用户实体User",required = true,dataType = "User")
    @PostMapping("createUser")
    public String post(@RequestBody User user){

        System.out.println("UserControllerRestfulAPI.post" + user);
        users.put(user.getId(),user);

        System.out.println("UserController.post");
        return "success";
    }

    @ApiOperation(value = "更新用户",notes = "根据用户id更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String"),
            @ApiImplicitParam(name = "user",value = "用户实体User",required = true,dataType = "User")
    })
    @PutMapping("updateUser/{id}")
    public String put(@PathVariable String id,@RequestBody User user){
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id,u);
        System.out.println("UserController.put");
        return "success";
    }

    @ApiOperation(value = "查询用户详情")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
    @GetMapping(value = "userDetail/{id}")
    public User detail(@PathVariable String id){
        System.out.println("UserController.detail");
        return users.get(id);
    }

    @ApiOperation(value = "删除用户")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
    @DeleteMapping(value = "deleteUser/{id}")
    public String delete(@PathVariable String id){
        users.remove(id);
        System.out.println("UserController.delete");
        return "success";
    }

}

代码写完了，下面我们来启动项目测试一下。

项目启动后，在浏览器输入：http://localhost:8080/swagger-ui.html  来访问swagger页面，如图：

 

先测试创建用户，填写测试数据，点击左下角的 Try it out 按钮

返回结果：

 

好了到此为止，我们的swagger整合springboot就完成了，有什么问题请随时指教。

 

参考文档：https://swagger.io/

http://blog.didispace.com/springbootswagger2/