详谈Springfox与swagger的整合使用

 更新时间:2017年08月01日 14:11:30   投稿:jingxian  
下面小编就为大家带来一篇详谈Springfox与swagger的整合使用。小编觉得挺不错的,现在就分享给大家,也给大家做个参考。一起跟随小编过来看看吧

一、前言

让我们先理一下springfoxswagger的关系。

swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI SpecificationOAS)为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。

OAS本身是一个API规范,它用于描述一整套API接口,包括一个接口是GET还是POST请求啊,有哪些参数哪些header啊,都会被包括在这个文件中。它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。

由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来,同时springfox也是一个新的项目,本文仍然是使用其中的一个组件springfox-swagger2

pringfox-swagger2依然是依赖OSA规范文档,也就是一个描述APIjson文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。

这是入门,我们简单地介绍springfox-swagger2的配置,帮助各位顺利地实现使用,文中有很多自己的理解,若有错误,欢迎批评指正。

二、配置流程说明

在开始编码之前,我们先对配置的流程有个大致的了解。

在前言中,我们知道,我们的第一个任务就是生成一个满足OSA规范的json文件(当然,创建一个spring的项目就不说了)。对于这个任务,springfox为我们提供了一个Docket(摘要的意思)类,我们需要把它做成一个Bean注入到spring中,显然,我们需要一个配置文件,并通过一种方式(显然它会是一个注解)告诉程序,这是一个Swagger配置文件。

一个OSA规范文档需要许多信息来描述这个APIspringfox允许我们将信息组合成一个ApiInfo的类,作为构造参数传给Docket(当然也可以不构造这个类,而直接使用null,但是你的这个API就太low了)。

接下来,我们要写控制器了,当然这不重要,不用springfox你依然要写控制器,重要的是要告诉springfox,这个控制器是一个需要他来收集API信息的控制器,不用说,这依然会采用注解的方式,同时,我们为了将配置文件与控制器结合起来,需要在配置文件中指明在什么位置收集可能是API的控制器的信息。

到这里,生成OSA规范的json文件的配置就结束了。虽然生成过程比我叙述的更复杂,但这些程序都会帮我们完成,我们可以通过类似http://localhost:8080/demo/v2/api-docs的路径来查看这个json文件。这个v2/api-docs就是springfox默认的生成文档的路径。

接下来,我们需要将它可视化显示出来,如果使用swagger-springmvc,我们需要单独去下载一个swagger ui的显示页面包,并将其中的路径改为上面的http://localhost:8080/demo/v2/api-docs,这里你就可以感受到,swagger ui就是在解析一个json文件了。你依然可以这么做,不过springfox专门提供了一个springfox-swagger-ui组件,不需要配置,我们只需要引入这个依赖的组件就可以看到最终的效果了,而这个路由会是http://localhost:8080/demo/swagger-ui.html

三、引入依赖

如果我写的不错,相信看到这里,你就大致了解了springfox swagger2的使用流程了。那么,我们进入正式编码的第一步:引入依赖。

这里我们使用maven引入依赖,大家可以到http://mvnrepository.com上搜索springfox,便可以看到Springfox Swagger2Springfox Swagger Ui,然后就可以从中获取最新的资源了。如下:

<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>

此外还需要一个依赖组件:

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.6.6</version>
</dependency>
 

四、一个简单的配置文件

为了清晰,我们可以先在常用的源码包里建一个config目录,并在里面创建一个SwaggerConfig.java文件,这是一个spring的配置文件,所以位置和文件名都影响不大。

先上代码:

@Configuration //必须存在
@EnableSwagger2 //必须存在
@EnableWebMvc //必须存在
@ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必须存在 扫描的API Controller package name 也可以直接扫描class (basePackageClasses)
public class SwaggerConfig{
 @Bean
 public Docket customDocket() {
  return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo());
 }

 private ApiInfo apiInfo() {
  Contact contact = new Contact("小明", "https://www.jb51.net/", "zhaomin0018@126.com");
  return new ApiInfoBuilder()
    .title("前台API接口")
    .description("前台API接口")
    .contact(contact)
    .version("1.1.0")
    .build();
 }
}

由于各位肯定用的是IDE,这里就不写各种import了。

首先,这个SwaggerConfig类有四个注解,看名称就可以明白是什么意思。其中,@Configuration,@EnableWebMvc和@ComponentScan是Spring的注解,而@EnableSwagger2则是用来启动Swagger支持,表示这是一个Spring Swagger的配置文件。

之后,定义了一个Bean方法CustomDocket,Spring中名字并不重要,重要的是它返回一个Docket类,DocumentationType.SWAGGER_2作为Docket构造方法的参数,指定了所用的swagger版本2.0,官网上已经在预告3.0版本了。而之后的apiInfo则是调用接下来的apiInfo函数,来创建Docket的信息。apiInfo函数采用ApiInfoBuilder来创建ApiInfo类。

五、一个控制器

其实,控制器不需要配置,就已经会被springfox swagger识别了,不过我们这里象征性地加上一个描述信息:

@Controller
@RequestMapping("/test")
public class TestController {
 @ApiOperation(value="一个测试API",notes = "第一个测试api")
 @ResponseBody
 @RequestMapping(value = "/hello",method = RequestMethod.GET)
 public String hello()
 {
  return "hello";
 }
}
 

这里仅仅多了一个@ApiOperation注解,别的和一个普通的springmvc的控制器完全一致。

实际上,为了形成一个完整的api文档,需要添加的注解常常很多,若是都写在同一个文件里就会显得臃肿,我们常常会写一个接口文件,将注解都放在接口文件中,然后再用一个实体类来实现控制器,算是实现配置和逻辑分离了吧。

六、查看接口文件和文档

若是没有问题,现在可以部署项目,并打开http://localhost:8080/demo/v2/api-docs

Firefox提供了查看JSON的插件,推荐大家搜索试试看。

废话不多说,这里可以看到之前配置的诸多信息。注入descriptionversiontitle等。并且确实有TestController的信息。

最后,我们打开http://localhost:8080/swagger-ui.html,便可以看到一个漂亮的界面了:

以上这篇详谈Springfox与swagger的整合使用就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持脚本之家。

相关文章

  • java小程序之控制台字符动画的实现

    java小程序之控制台字符动画的实现

    这篇文章主要给大家介绍了java小程序之控制台字符动画实现的相关资料,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2021-04-04
  • java遍历http请求request的所有参数实现方法

    java遍历http请求request的所有参数实现方法

    下面小编就为大家带来一篇java遍历http请求request的所有参数实现方法。小编觉得挺不错的,现在就分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2016-09-09
  • Java使用volatile关键字的注意事项

    Java使用volatile关键字的注意事项

    volatile关键字是Java中的一种稍弱的同步机制,为什么称之为弱机制。这篇文章主要介绍了Java使用volatile关键字的注意事项,需要的朋友可以参考下
    2017-02-02
  • SpringCloud中的Ribbon负载均衡详细解读

    SpringCloud中的Ribbon负载均衡详细解读

    这篇文章主要介绍了SpringCloud中的Ribbon负载均衡详细解读,当系统面临大量的用户访问,负载过高的时候,通常会增加服务器数量来进行横向扩展(集群),多个服务器的负载需要均衡,以免出现服务器负载不均衡,部分服务器负载较大,部分服务器负载较小的情况,需要的朋友可以参考下
    2023-11-11
  • springboot乱码问题排查思路解析

    springboot乱码问题排查思路解析

    这篇文章主要为大家介绍了springboot乱码问题排查思路解析,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-06-06
  • 带你详细了解Spring Security的注解方式开发

    带你详细了解Spring Security的注解方式开发

    这篇文章主要介绍了详解spring security四种实现方式,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2021-08-08
  • javaweb实现文件上传与下载功能

    javaweb实现文件上传与下载功能

    这篇文章主要为大家详细介绍了javaweb实现文件上传与下载功能,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2020-12-12
  • 使用Java8实现观察者模式的方法(上)

    使用Java8实现观察者模式的方法(上)

    本文给大家介绍使用java8实现观察者模式的方法,涉及到java8观察者模式相关知识,对此感兴趣的朋友一起学习吧
    2016-02-02
  • Java中基于推、拉模式的sentinel规则持久化详解

    Java中基于推、拉模式的sentinel规则持久化详解

    这篇文章主要介绍了Java中基于推、拉模式的sentinel规则持久化详解,推模式是sentinelDashboard 把规则推给Nacos,Nacos监听规则的变化推给微服务,拉模式是sentinelDashboard 把规则直接给微服务, Nacos定时的同步微服务端的规则,需要的朋友可以参考下
    2023-09-09
  • Java发送http请求调用第三方接口获取token方式

    Java发送http请求调用第三方接口获取token方式

    这篇文章主要介绍了Java发送http请求调用第三方接口获取token方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2023-07-07

最新评论