在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释

先介绍一下开发环境:

  1. jdk版本是1.8
  2. springboot的版本是1.4.1
  3. 开发工具为 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:用在方法上,说明方法的作用

  1.     value: 表示接口名称
  2.     notes: 表示接口详细描述 

@ApiImplicitParams:用在方法上包含一组参数说明

@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

  1. paramType:参数位置
  • header 对应注解:@RequestHeader
  • query 对应注解:@RequestParam
  • path  对应注解: @PathVariable
  • body 对应注解: @RequestBody
  1. name:参数名
  2. dataType:参数类型
  3. required:参数是否必须传
  4. value:参数的描述
  5. defaultValue:参数的默认值

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

  1. code:状态码
  2. message:返回自定义信息
  3. response:抛出异常的类

@ApiIgnore: 表示该接口函数不对swagger2开放展示

以上这些就是我测试过的注解,并没有深究,有兴趣的,可以看看其它注解,或者源码,会比我描述的全很多,

对了,需要注意下,@ApiImplicitParam注解下的paramType属性,会影响接口的测试,如果设置的属性跟spring的注解对应不上,会获取不到参数,例如:paramType=path,函数内却使用@RequestParam注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将@RequestParam注解改为@PathVariable才能获取到对应的参数...

springboot集成swagger2构建RESTful API文档的更多相关文章

  1. Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档

    前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...

  2. Spring Boot中使用Swagger2构建RESTful API文档

    在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...

  3. Spring Boot 集成Swagger2生成RESTful API文档

    Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...

  4. Spring Boot 集成 Swagger 生成 RESTful API 文档

    原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...

  5. spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

    spring boot / cloud (三) 集成springfox-swagger2构建在线API文档 前言 不能同步更新API文档会有什么问题? 理想情况下,为所开发的服务编写接口文档,能提高与 ...

  6. 集成swagger2构建Restful API

    集成swagger2构建Restful API 在pom.xml中进行版本管理 <swagger.version>2.8.0</swagger.version> 给taosir ...

  7. spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档

    文章目录 一.Springfox 与 Swagger 简介 1.1 Springfox 1.2 Swagger 1.3 OpenApi.Swagger.Springfox的关系 二.spring bo ...

  8. 架构实战项目心得(十四):spring-boot结合Swagger2构建RESTful API测试体系

    一.添加依赖: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-s ...

  9. Spring Boot中使用Swagger2生成RESTful API文档(转)

    效果如下图所示: 添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!-- https://mvnrepository.com/artifact/io.springfox ...

随机推荐

  1. IIS调试技术之 Debug Diagnostic (调试诊断)

    IIS 调试技术之 Debug Diagnostic (调试诊断) 1      概述 1.1  文档简介 系统出现错误或崩溃,免不了要进行调试.调试能进行的前提是错误能重现,但实际上要重现一个错误有 ...

  2. 灵感一:搜索型APP,帮助读书爱好者,搜索某本书的关键字

    灵感来自生活,我在查询 javascript 高级程序设计 3的时候,由于我记不清楚,该关键字在书的某个地方,我就想,有没有这么一款APP,可以通过扫描一本书的二维码,自动下载该书的内容,然后再通过搜 ...

  3. 【5】.net WCF 简单实例

    1.创建WCF项目 2.系统自动生成IWcfService // 注意: 使用“重构”菜单上的“重命名”命令,可以同时更改代码和配置文件中的接口名“IService1”. [ServiceContra ...

  4. Asp.NET MVC4 + Ajax 实现多文件上传

    本文转自http://www.cnblogs.com/freeliver54/archive/2013/05/15/3079700.html JS部分测试可以,jQuery部分没有测试先留着 HTML ...

  5. springboot伪静态

    在日常网站访问中,会把动态地址改造成伪静态地址. 例如: 访问新闻栏目 /col/1/,这是原有地址,如果这样访问,不利于搜索引擎检索收录,同时安全性也不是很好. 改造之后: /col/1.html. ...

  6. lintcode题目记录4

    Russian Doll Envelopes    Largest Divisible Subset     Two Sum - Input array is sorted Russian Doll ...

  7. axios拦截器请求头携带token

    转—— https://github.com/superman66/vue-axios-github/blob/master/src/http.js

  8. dotnet watch+vs code提升asp.net core开发效率

    在园子中,已经又前辈介绍过dotnet watch的用法,但是是基于asp.net core 1.0的较老版本来讲解的,在asp.net core 2.0的今天,部分用法已经不太一样,所以就再写一篇文 ...

  9. CentOS7 下安装 SublimeText3

    原文地址:http://www.sundabao.com/centos-%E5%AE%89%E8%A3%85sublime-text-3/ Centos 安装Sublime text 3 Centos ...

  10. 六、使用media实现响应式布局

    常见写法: 下面总结常见的响应式布局的分类: @media screen and (max-width:320px){ #talkFooter .editArea{…… } } @media scre ...