springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释
先介绍一下开发环境:
- jdk版本是1.8
- springboot的版本是1.4.1
- 开发工具为 intellij idea
我们先引入swagger2的jar包,pom文件引入依赖如下:
<dependency><groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
接下来,我们构建swagger2的配置类,代码如下:
//注解开启 swagger2 功能
@EnableSwagger2
//注解标示,这是一个配置类,@Configuation注解包含了@Component注解 //可以不用在使用@Component注解标记这是个bean了, @Configuration public class Swagger2 { /** * 通过 createRestApi函数来构建一个DocketBean * 函数名,可以随意命名,喜欢什么命名就什么命名 */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容 .select() //控制暴露出去的路径下的实例 //如果某个接口不想暴露,可以使用以下注解 //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下 .apis(RequestHandlerSelectors.basePackage("com.example")) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("Spring Boot 测试使用 Swagger2 构建RESTful API") //创建人 .contact("贺小五") //版本号 .version("1.0") //描述 .description("API 描述") .build(); } }
swagger2的配置类已经配置好了,下面,我们就在主函数里面随意写一些接口吧
@SpringBootApplication(scanBasePackages = {"com"})
//该注解包含了@Controller和@ResponseBody两个注解
@RestController public class DemoApplication{ public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } /** * 以下函数的注释,不增加注解了,将在下面统一做描述 */ @ApiOperation(value = "测试post请求",notes="注意事项") @ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true) @RequestMapping(value = "/testPost",method = RequestMethod.POST) public String testPost(@RequestBody User user){ return "success"; } @ApiOperation(value = "测试get请求",notes="注意事项") @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",paramType = "path") @RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET) public String testGet(@PathVariable String id){ return id; } @ApiOperation(value = "测试组合注解",notes="注意事项") @ApiImplicitParams({ @ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true,paramType = "body"), @ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true,paramType = "path") }) @RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST) public User joinAnnotation(@PathVariable String id,@RequestBody User user){ return user; } @ApiIgnore public String testIgnore(){ return "success"; } }
你们别吐槽我的方法命名........将就着看吧...测试demo,命名随意了些(其实是我英语不太好....哈哈哈哈哈.....)
写好controller后,我们可以访问以下地址:http://localhost:8080/swagger-ui.html,如果你没引入swagger2依赖,你是访问不了的..然后你会得到一个如下页面
上面的页面,就是swagger2里面的页面,可以发现, apiInfo里面设置的内容在左边展示出来了,demo-application其实就是controller的类名,右边有三个按钮,分别是 Show/Hide,List Opertions和Expand Operations,三个按钮都可以打开,类下的接口,点击后,会得到如下一个效果页面:
可以发现,展示出来了,controller下的三个接口(其实有四个,只不过有一个我们用注解忽略了,在这不展示而已..)
上面三个接口,在我们注解里面添加的,都有展示,请求方式,接口名称,现在我们打开某个接口,看看具体内容,接口内的内容,我不在用文字描述,我直接在截图里面添加描述了.见谅....
这个,,截图比较烂,各位将就着看吧..别嫌弃...,我们点击try it out 按钮,就会发送请求,结果如下:
以上就是比较简单的demo测试文档啦,如果各位想配置更详细,就去官网看吧..地址我贴出来:
swagger官网地址:http://swagger.io/
下面就是介绍,上面接口中,上面关于swagger2本人常用注解的一些描述
本人常用注解说明:
@ApiOperation:用在方法上,说明方法的作用
- value: 表示接口名称
- notes: 表示接口详细描述
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- paramType:参数位置
- header 对应注解:@RequestHeader
- query 对应注解:@RequestParam
- path 对应注解: @PathVariable
- body 对应注解: @RequestBody
- name:参数名
- dataType:参数类型
- required:参数是否必须传
- value:参数的描述
- defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:状态码
- message:返回自定义信息
- response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
以上这些就是我测试过的注解,并没有深究,有兴趣的,可以看看其它注解,或者源码,会比我描述的全很多,
对了,需要注意下,@ApiImplicitParam注解下的paramType属性,会影响接口的测试,如果设置的属性跟spring的注解对应不上,会获取不到参数,例如:paramType=path,函数内却使用@RequestParam注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将@RequestParam注解改为@PathVariable才能获取到对应的参数...
springboot集成swagger2构建RESTful API文档相关推荐
- Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- SpringBoot集成knif4j创建在线API文档
一直以来能够创建一个同项目一起发布的在线文档,曾经是很多程序员的梦想,偶然发现这个工具已经有了,测试之后发现还挺好用的,特地纪念. 这个工具就是knife4j,它是为Java MVC框架集成Swagg ...
- springboot 集成 swagger 自动生成API文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...
- Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- SpringBoot集成swagger生成在线接口文档
SpringBoot集成swagger生成在线接口文档 集成maven依赖 <dependency><groupId>io.springfox</groupId>& ...
- Spring MVC中使用 Swagger2 构建Restful API
0.Spring MVC配置文件中的配置 [java] view plain copy <!-- 设置使用注解的类所在的jar包,只加载controller类 --> <span s ...
- Api2Doc,生成 Restful API 文档
Api2Doc 简介 Api2Doc 专注于 Restful API 文档的自动生成,它的原理与 Swagger2 是类似的, 都是通过反射,分析 Controller 中的信息生成文档,但它要比 S ...
最新文章
- Nucleus 实时操作系统中断(上)
- wannafly 12 删除子串 dp
- 混合密度网络(MDN)进行多元回归详解和代码示例
- Redis实战(2)安装和试用
- boost::mpl::minus相关的测试程序
- oracle:平均分大于78的女同学的学号、姓名、平均分
- [集训队作业2018] 复读机(生成函数,单位根反演)
- rsa加密算法python_模拟新浪微博登录(Python+RSA加密算法)
- python:当文件中出现特定字符串时执行robot用例
- 从Android上的相机裁剪图像
- 版权审查只会越来越严
- Android学习进阶路线导航线路(Android源码分享)
- 小米蓝牙驱动_小米降噪项圈蓝牙耳机:随时随地享受奢侈静谧空间
- IBM ThinkPad SL400 驱动全集下载
- 用html做网页作品,HTML5实例:用HTML5制作的网页的15个优秀案例
- mysql正则防注入_防止sql注入的方法
- 声卡中的 line in line out
- QQ空间蜘蛛爬虫数据报告
- rn在java中什么意思,RN150中RN是什么意思
- mtk平台gsensor,msensor方向确定方法