springboot 学习笔记【5】使用Swagger2构建RESTful APIs
2017-06-09 11:20
866 查看
摘要: springboot 学习笔记 swagger
接上一篇springboot 学习笔记【4】Spring Boot构建RESTful API
上一篇博客中写了一个简单的Restful接口的服务,在实际开发中我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创- - 建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面两个问题,有一个开源工具可以帮助我们快速构建Restful接口文档。swagger
下面我们将上一篇博客的源代码添加Swagger。
###添加swagger依赖
###创建Swagger2配置类
在main函数同级目录创建swagger2类。
如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
###添加文档内容
在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
就能看到前文所展示的RESTful API的页面。
我们可以再点开具体的API请求,以GET类型的/users/findall请求为例,点击 Try it out结果如下
完整工程
接上一篇springboot 学习笔记【4】Spring Boot构建RESTful API
上一篇博客中写了一个简单的Restful接口的服务,在实际开发中我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创- - 建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面两个问题,有一个开源工具可以帮助我们快速构建Restful接口文档。swagger
下面我们将上一篇博客的源代码添加Swagger。
###添加swagger依赖
<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类。
@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注解来给参数增加说明。
@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 = use 3ff0 rRepository.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的页面。
我们可以再点开具体的API请求,以GET类型的/users/findall请求为例,点击 Try it out结果如下
完整工程
相关文章推荐
- Spring Boot中使用Swagger2构建RESTful APIs
- Springboot中使用Swagger2构建RESTful APIs
- Spring Boot中使用Swagger2构建RESTful APIS(含源码)
- springboot 学习笔记【3】使用Swagger2构建RESTful APIs
- springboot中使用swagger2构建restful接口文档
- Springboot中使用Swagger2构建RESTful API文档
- Spring Boot 2.0.0.M7 中使用Swagger2构建RESTful API文档
- 在spring-boot中使用swagger2来构建RESTful API文档
- 01.Spring Cloud学习笔记之使用IDEA+Spring Boot快速构建Rest服务
- 使用 Spring Boot 快速构建 Spring 框架应用---学习笔记
- springboot 学习笔记【4】Spring Boot中使用Spring-data-jpa
- Spring Boot中使用Swagger2构建强大的RESTful API文档
- spring boot 学习笔记(二) 构建web支持jsp
- Spring Boot 学习笔记【6】使用FreeMarker与BootStrap开发Web
- spring cloud-整合Swagger2构建RESTful服务的APIs
- SpringBoot,SpringCloud,Docker构建微服务学习笔记
- spring cloud 集成 swagger2 构建Restful APIS 说明文档
- 使用spring boot快速构建一个RESTful Web Service
- Spring Boot中使用Swagger2构建强大的RESTful API文档
- Spring Boot中使用Swagger2构建强大的RESTful API文档