RESTful API的灵魂伴侣——Swagger
开篇总是要写一些概括性的东西!
Swagger 是一个RESTful接口的文档的实时生成与测试工具。没接触过类似工具的你可能对这句话没什么概念,不要急,我来慢慢解释。
使用REST的原因之一就是方便前后端分离开发,后端开发者写后端的逻辑,前端开发者写前端的逻辑,然后大家约定好一个API的风格,使用HTTP的get、post、put、delete来对应资源的CURD。避免了这种情况的发生:前端开发者拿着后端提供的厚厚的API文档边查阅边愤愤地开发,每个业务逻辑对应一个接口规范,混乱不堪。然后某一天后端改了逻辑,删掉了几个接口又增加了几个接口,前端又要大范围地改代码,然后前后端就打起来了。
为了避免打架,规范了API的设计,使用了较为轻便的RESTful风格。而Swagger起到一个锦上添花的作用,它使得前后端的协同变得更加效率。后端开发者在定义好接口后,Swagger会自动生成并更新文档,文档中会详细记录接口的使用方法,需要传入哪些参数,又会返回什么样的结果,即节约了写文档的时间,又提高了文档的同步速度,提高了开发效率。另外Swagger不止这些功能,它还有一个强大的功能,就是在文档中直接对接口进行测试,我们可以使用Swagger模拟用户的真实操作,向后台发一个请求来验证接口是否满足需求。说了这么多,可能你还是不太明白,那我直接贴张图片吧,下图就是Swagger生成的文档:
算了,不截图了,直接给个链接吧:http://petstore.swagger.io/?_ga=2.151670393.1145939008.1514200525-1067691787.1514200525
这是官方提供一个demo文档,可以简单操作一下,聪明的你应该豁然开朗了吧!
好了,Swagger介绍完了,相信大家已经认识他了吧。下面我将介绍如何在spring mvc项目中嵌入Swagger:
本文使用 springfox-swagger实现Swagger的集成。很简单,仅仅几步就可搞定!
步骤↓:
-
引入jar包,此处笔者使用maven,直接引入依赖:
<!-- swagger RestfulAPI 文档工具 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox.version}</version> </dependency>
此处使用的版本是springfox.version=2.6.1 - 重写一下Swagger的配置类并声明成bean:
package com.ds.core.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @EnableWebMvc @EnableSwagger2 @ComponentScan("com.ds.literary.controller")//配置Swagger要扫描的包 @Configuration public class SwaggerConfig extends WebMvcConfigurationSupport { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("Du") .select() // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } // @Bean // public Docket xxx() { // return new Docket(DocumentationType.SWAGGER_2) // .apiInfo(apiInfo()) // .groupName("xxx") // .select() // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // .paths(PathSelectors.ant("/xxx/**")) // .build(); // } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Ds") .contact(new Contact("Du", "", "981040863@qq.com")) .version("0.0.1") .build(); } }
- 在写controller的时候加入一些annotation就好了:
@RestController @RequestMapping("/blog") @Api(value = "管理用户发表的博客,文章,日志接口", description = "管理用户发表的博客,文章,日志接口") public class BlogController extends BaseController<Blog>{ public String getService() { return "blogService"; } @PutMapping @ApiOperation(value = "修改用户发表的博客,文章,日志", produces = MediaType.APPLICATION_JSON_VALUE) public Object update(HttpServletRequest request, @RequestBody Blog param) { ModelMap modelMap = new ModelMap(); long authorId=getCurrUser(); param.setAuthorId(authorId); return super.update(modelMap, param); } @DeleteMapping @ApiOperation(value = "删除用户发表的博客,文章,日志", produces = MediaType.APPLICATION_JSON_VALUE) public Object delete(HttpServletRequest request, @RequestBody Blog param) { ModelMap modelMap = new ModelMap(); return super.delete(modelMap, param); } }
- 在spring中配置一个资源重定向:
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
- 启动项目,打开默认文档界面http://localhost:8080/ds-sys-web/swagger-ui.html,这个路径根据你的实际情况修改。如果你觉得这个界面丑,是可以自己定制的,具体方法本篇就不介绍了。
下面是成功后的截图:
搞定!
推荐阅读
-
遇到项目RESTful改造时怎么用ajax的$post方法请求api接口?
-
PHPer的项目RESTful API设计规范是怎样的?
-
Java 调用Restful API接口的几种方式(HTTPS)
-
【从零开始搭建自己的.NET Core Api框架】(一)创建项目并集成swagger:1.2 完善
-
yii2的restful api路由实例详解
-
.NET Core利用swagger进行API接口文档管理的方法详解
-
深度好文:寻找灵魂深处的伴侣
-
RESTful API批量操作的实现
-
使用Node.js实现RESTful API的示例
-
Python实现的Flask一个RESTful API 服务器端测试