Springboot中集成Swagger2框架的方法

摘要:在项目开发中,往往期望做到前后端分离,也就是后端开发人员往往需要输出大量的服务接口,接口的提供方无论是是Java还是PHP等语言,往往会要花费一定的精力去写接口文档,比如A接口的地址、需要传递参数情况、返回值的JSON数据格式以及每一个字段说明、当然还要考虑HTTP请求头、请求内容等信息。随着项目的进度快速高速的迭代,后端输出的接口往往会面临修改、修复等问题,那也意味着接口文档也要进行相应的调整。接口文档的维护度以及可读性就大大下降。

既然接口文档需要花费精力去维护,还要适当的进行面对面交流沟通,我们何不想一个办法,第一:可以不用写接口文档;第二:前端与后端沟通接口问题的时候,后端是否可以提供一个URL,在这个URL中罗列出所有可以调用的服务接口,并在每个服务接口中罗列出参数的说明,返回值的说明,第三:后端接口如果能模拟调用就所有问题都解决了。本文我们重点讲解一下Sringboot中集成Swagger2框架。

1.1. 添加Swagger2依赖

在项目的pom.xml文件中增加如下的依赖。

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

首先,我们需要建立一个启动类,代码如下:

@SpringBootApplication
public class Application {
 public static void main(String[] args) {
 SpringApplication.run(Application.class, args);
 }
}

然后在上述类的同级目录中新建swagger2的配置类如下所示:

@Configuration
@EnableSwagger2
public class Swagger2 {
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.shareniu.web"))
        .paths(PathSelectors.any())
        .build();
  }
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("跟着分享牛学习Springboot源码分析系列课程")
        .description("更多Spring Boot相关文章请关注分享牛的博客")
        .termsOfServiceUrl("http://www.shareniu.com/")
        .contact("牛牛")
        .license("Copyright 2017-2018 分享牛")
        .version("1.0")
        .build();
  }
}

@Configuration制定了spring要加载这个类,@EnableSwagger2注解要开启Swagger功能。

上述中的ApiInfo最终都会展现在前端,我们使用了扫描包的方式配置配置,也就是RequestHandlerSelectors.basePackage。在这个包以及子包中的控制器最终都是生成API文档。(除了被@ApiIgnore注解指定的请求)。

1.2. 新增文档说明

上述的类声明之后,我们其实就可以直接调用了,但是为了增加文档的可读性,我们还是需要在接口中增加一些说明,我们先写一个控制器如下所示:

@RestController
@RequestMapping(value="/users")
public class UserController {
  static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
  static {
   User user = new User();
   user.setAge(18);
   user.setId(1L);
   user.setName("aa");
   users.put(1L, user);
  }
  @ApiOperation(value="获取所有用户列表", notes="")
  @RequestMapping(value={""}, method=RequestMethod.GET)
  public List<User> getUserList() {
    List<User> r = new ArrayList<User>(users.values());
    return r;
  }
  @ApiOperation(value="创建新的用户", notes="根据User对象创建用户")
  @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postUser(@RequestBody User user) {
    users.put(user.getId(), user);
    return "success";
  }
  @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
  @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.GET)
  public User getUser(@PathVariable Long id) {
    return users.get(id);
  }
  @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
      @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  })
  @RequestMapping(value="/{id}", method=RequestMethod.PUT)
  public String putUser(@PathVariable Long id, @RequestBody User user) {
    User u = users.get(id);
    u.setName(user.getName());
    u.setAge(user.getAge());
    users.put(id, u);
    return "success";
  }
  @ApiOperation(value="删除已存在的用户", notes="根据url的id来指定删除对象")
  @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
  public String deleteUser(@PathVariable Long id) {
    users.remove(id);
    return "success";
  }
}

@ApiOperation:用来描述该接口的作用。可以通过该注解说明接口的职责、返回头信息、方法的请求方式("GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH")、协议( http, https, ws, wss)、http状态码。
@ApiImplicitParam:用来给参数增加说明。可以设置参数的名称、是否是必填项、参数的描述信息、是否只读等。

上述代码提交之后,启动springboot,访问http://127.0.0.1:8080/swagger-ui.html,如下图所示:

上图分为两个部分,上部分是通过Swagger2类配置出来的,下半部分是UserController类中的接口文档。
这里我们以/user为例进行说明:

点击/user如下图所示:

上图黄色的地方表示,该接口返回的样例数据。也就是User的数据结构。Response Content Type:接口返回的头信息。点击Try it out。如下所示:

该接口返回的baody、code码、响应头已经成功返回了。

总结

以上所述是小编给大家介绍的Springboot中集成Swagger2框架的方法,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对我们网站的支持!

(0)

相关推荐

  • Spring Boot 整合mybatis 与 swagger2

    之前使用springMVC+spring+mybatis,总是被一些繁琐的xml配置,有时候如果配置出错,还要检查各种xml配置,偶然接触到了spring boot 后发现搭建一个web项目真的是1分钟的事情,再也不用去管那么多xml配置,简直神清气爽,不用看那么多一坨xml,下面是我把以前的一些ssm项目改成了spring boot + mybatis,相对于来说优点太明显了 1. 创建独立的Spring应用程序 2. 嵌入的Tomcat,无需部署WAR文件 3. 简化Maven配置 4. 自

  • Spring Boot集成springfox-swagger2构建restful API的方法教程

    前言 之前跟大家分享了Spring MVC集成springfox-swagger2构建restful API,简单写了如何在springmvc中集成swagger2.这边记录下在springboot中如何集成swagger2.其实使用基本相同. 方法如下: 首先还是引用相关jar包.我使用的maven,在pom.xml中引用相关依赖(原来我使用的是2.2.0的,现在使用2.4.0的): <dependency> <groupId>io.springfox</groupId&g

  • SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)

    pom.xml增加依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <

  • spring boot整合Swagger2的示例代码

    Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 1.代码示例 1).在pom.xml文件中引入Swagger2 <dependency> <groupId>io.springfox</groupId> <artifa

  • Springboot中集成Swagger2框架的方法

    摘要:在项目开发中,往往期望做到前后端分离,也就是后端开发人员往往需要输出大量的服务接口,接口的提供方无论是是Java还是PHP等语言,往往会要花费一定的精力去写接口文档,比如A接口的地址.需要传递参数情况.返回值的JSON数据格式以及每一个字段说明.当然还要考虑HTTP请求头.请求内容等信息.随着项目的进度快速高速的迭代,后端输出的接口往往会面临修改.修复等问题,那也意味着接口文档也要进行相应的调整.接口文档的维护度以及可读性就大大下降. 既然接口文档需要花费精力去维护,还要适当的进行面对面交

  • SpringBoot中集成企业微信机器人实现运维报警的示例

    目录 1.注册企业微信 2.添加群机器人 3.引入 forest 依赖 4.请求方法 5.发送消息 6.测试 在企业运营中,为了实现工作效率和执行效率的提升,往往会选择在社群中使用群聊机器人进行协助管理.机器人可以定时或者按照一定的规则给群里发信息并@群成员等.群聊机器人可以活跃气氛,关怀员工比如根据天气情况提醒员工注意天气变化,发送节日.生日祝福等.它也可以进行工作提醒,帮助员工更好的做系统化的回报总结,机器人可以依托业务系统,每天定时发送工作总结给对应负责人,帮助员工更好地复盘工作. 1.注

  • JavaWeb工程中集成YMP框架快速上手(二)

    本文将介绍如何在Java Web工程中集成YMP框架,操作过程基于IntelliJ IDEA做为开发环境,工程结构采用Maven构建: IntelliJ IDEA下载地址: https://www.jetbrains.com/idea/download/ Maven下载地址: http://maven.apache.org/ 创建项目 1. 打开IDEA开发环境并点击Create New Project按钮开始创建新项目向导,如下图-1所示: 2. 在New Project窗口中选中左侧Mave

  • 在SpringBoot中添加Redis及配置方法

    在实际的开发中,会有这样的场景.有一个微服务需要提供一个查询的服务,但是需要查询的数据库表的数据量十分庞大,查询所需要的时间很长. 此时就可以考虑在项目中加入缓存. 引入依赖 在maven项目中引入如下依赖.并且需要在本地安装redis. <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifac

  • 一篇文章带你搞定SpringBoot中的热部署devtools方法

    一.前期配置 创建项目时,需要加入 DevTools 依赖 二.测试使用 (1)建立 HelloController @RestController public class HelloController { @GetMapping("/hello") public String hello(){ return "hello devtools"; } } 对其进行修改:然后不用重新运行,重新构建即可:只加载变化的类 三.热部署的原理 Spring Boot 中热部

  • 教你在Spring Boot微服务中集成gRPC通讯的方法

    一.首先声明gRPC接口 这里引入的是最新的gRpc-core 1.37版本, 采用的grcp-spring-boot-starter封装的版本进行实现,github地址: https://github.com/yidongnan/grpc-spring-boot-starter 要实现gRpc通讯, 先定义接口以及入参出参信息 syntax = "proto3"; option java_multiple_files = true; option java_package = &qu

  • springboot如何集成Swagger2

    一.是什么 当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成.在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率.传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本.而 Swagger 给我们提供了一个全新的维护 API 文档的方式. 二.为什么要使用它 1.代码变更,文档跟着代码变.只需要少量的注解Swagger就可以根据

  • 详细聊聊SpringBoot中动态切换数据源的方法

    其实这个表示有点不太对,应该是 Druid 动态切换数据源的方法,只是应用在了 springboot 框架中,准备代码准备了半天,之前在一次数据库迁移中使用了,发现 Druid 还是很强大的,用来做动态数据源切换很方便. 首先这里的场景跟我原来用的有点点区别,在项目中使用的是通过配置中心控制数据源切换,统一切换,而这里的例子多加了个可以根据接口注解配置 第一部分是最核心的,如何基于 Spring JDBC 和 Druid 来实现数据源切换,是继承了org.springframework.jdbc

  • idea 在springboot中使用lombok插件的方法

    在idea中添加lombok插件 选择 file-->setting--->plugins  搜索lombok  并安装插件后重启idea 使用Lombok 在pom.xml中引入依赖 <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.10</version> <s

  • JavaWeb工程中集成YMP框架快速上手

    了解YMP框架 YMP于2014年10月25日正式发布1.0版本,在此之前就已在实际项目中得到广泛使用,从最初仅限团队内部使用,到合作伙伴的开发团队,再到身边的朋友,和朋友的朋友们也开始将YMP投入到实际项目中去,所以在这里我要向一直以来帮助.支持我的这些同事.朋友们表示衷心的感谢!是大家的信赖和对它的认可,才使得YMP快速成长起来,在变化过程中它一直在不断的改进.优化直至最终对外发布. 没有完美的框架,只有适合的才是好的,为了让YMP更简单易用,从2015年1月26日正在开始了v2版本的开发,

随机推荐