开篇总是要写一些概括性的东西!
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 API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又...
Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API...
Python Flask高级编程之RESTFul API前后端分离精讲Python Flask高级编程之RESTFul API前后端分离精讲Python Flask高级编程之RESTFul API前后端分离精讲Python Flask高级编程之RESTFul API前后端分离精讲Python Flask...
Python Flask高级编程之RESTFul API前后端分离精讲第二章节Python Flask高级编程之RESTFul API前后端分离精讲第二章节Python Flask高级编程之RESTFul API前后端分离精讲第二章节Python Flask高级编程之RESTFul API...
thinkphp6 RESTful API开发 开发过程记录笔记 https://blog.csdn.net/weixin_41120504/article/details/115638094
此代码通过c c++实现一个简单的http服务,可以用此实现一个restful api 服务器.
restful api 接口说明. 总结 restful api 语法知识和常用的状态码含义.
RESTful API设计规范.pdf
SpringBoot+Mybatis+CXF框架,实现Restful api与 WebService api接口的大实验
RESTful API设计规范
restful api访问k8s集群,增删改查信息。 需要预先创建访问权限的配置。 官网api文档 https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/ 下面罗列部分api curl -u admin:admin ...
swagger提供的接口文档相比传统的文档方式更加直观也更加高效,但是在网上找了很多关于Swagger与SpringMvc整合的资料,发现都比较繁琐,不是很满意,于是有了这篇博客,希望对大家有所帮助。教程:...
Spring Boot 整合 Mybatis 实现RESTful API ,具体可以查看博客: http://blog.csdn.net/yaozhiqi1905658804/article/details/70820892
Spring boot restful api demo
springboot入门demo...实现了restful api和webservice两种接口方式。(可通过postman或soupui进行测试。) 同时包含了Junit测试webservice。 Demo是经过亲测完全可以跑起来。通过此demo可对springboot有个入门的理解
RestFul API 案例 新手入门帮助 包括RestFul 和RestFul Api的介绍 也包括案例代码
REST它是一种使用URL来定位资源,使用HTTP请求描述操作的Web服务规范,本资源包含RESTful简介、设计原则、通用说明、规范细则、接口管理说明。
RestfulApi服务端demo,需要RestfulApi客户端的到此处下载:https://download.csdn.net/download/qq_44020228/15491219
Python语言开发RESTful API指南,完整介绍了开发的方方面面。
Python Flask高级编程之RESTFul API前后端分离精讲第五章节Python Flask高级编程之RESTFul API前后端分离精讲第五章节Python Flask高级编程之RESTFul API前后端分离精讲第五章节Python Flask高级编程之RESTFul API...