接上一篇springboot 学习笔记【4】Spring Boot构建RESTful APIhtml
上一篇博客中写了一个简单的Restful接口的服务,在实际开发中咱们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减小与其余团队平时开发期间的频繁沟通成本,传统作法咱们会建立一份RESTful API文档来记录全部接口细节,然而这样的作法有如下几个问题:git
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>
###建立Swagger2配置类 在main函数同级目录建立swagger2类。spring
@Configuration @EnableSwagger2 public class swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //Restful接口的basepackage .apis(RequestHandlerSelectors.basePackage("pub.zhouhui.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .version("1.0") .build(); } }
如上代码所示,经过@Configuration注解,让Spring来加载该类配置。再经过@EnableSwagger2注解来启用Swagger2。 再经过createRestApi函数建立Docket的Bean以后,apiInfo()用来建立该Api的基本信息(这些基本信息会展示在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展示,本例采用指定扫描的包路径来定义,Swagger会扫描该包下全部Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。 ###添加文档内容 在完成了上述配置后,其实已经能够生产文档内容,可是这样的文档主要针对请求自己,而描述主要来源于函数等命名产生,对用户并不友好,咱们一般须要本身增长一些说明来丰富文档内容。以下所示,咱们经过@ApiOperation注解来给API增长说明、经过@ApiImplicitParams、@ApiImplicitParam注解来给参数增长说明。api
@RestController @RequestMapping(value="/user") public class UserController { @Autowired private UserRepository userRepository; @ApiOperation(value="获取用户列表", notes="") @RequestMapping(value="/findall",method= RequestMethod.GET) public List<User> findall(){ List<User> alluser = userRepository.findAll(); return alluser; } @ApiOperation(value="经过ID查找用户", notes="") @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable String id) { // 处理"/users/{id}"的GET请求,用来获取url中id值的User信息 // url中的id可经过@PathVariable绑定到函数的参数中 return userRepository.findByName(id); } @ApiOperation(value="建立用户", notes="根据User对象建立用户") @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") @RequestMapping(value="/add", method=RequestMethod.POST) public String addUser(@RequestBody User user){ User users = new User(); users.setId(user.getId()); users.setName(user.getName()); users.setAge(user.getAge()); userRepository.save(users); return "success"; } @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") }) @RequestMapping(value="/update/{id}", method=RequestMethod.POST) public String updateUser(@PathVariable long id, @RequestBody User user){ User users = new User(); users.setId(id); users.setName(user.getName()); users.setAge(user.getAge()); userRepository.save(users); return "success"; } @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deldeteUser(@PathVariable long id) { // 处理"/users/{id}"的GET请求,用来获取url中id值的User信息 // url中的id可经过@PathVariable绑定到函数的参数中 userRepository.delete(id); return "success"; } }
完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html 就能看到前文所展现的RESTful API的页面。 springboot
咱们能够再点开具体的API请求,以GET类型的/users/findall请求为例,点击 Try it out结果以下 app
完整工程函数