Springfox与swagger的整合使⽤与关系
⼀、前⾔
让我们先理⼀下springfox与swagger的关系。
swagger是⼀个流⾏的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个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规范⽂档，也就是⼀个描述API的json⽂件，⽽这个组件的功能就是帮助我们⾃动⽣成这个json⽂件，我们会⽤到的另外⼀个组件springfox-swagger-ui就是将这个json⽂件解析
出来，⽤⼀种更友好的⽅式呈现出来。
这是⼊门，我们简单地介绍springfox-swagger2的配置，帮助各位顺利地实现使⽤，⽂中有很多⾃⼰的理解，若有错误，欢迎批评指正。
⼆、配置流程说明
在开始编码之前，我们先对配置的流程有个⼤致的了解。
在前⾔中，我们知道，我们的第⼀个任务就是⽣成⼀个满⾜OSA规范的json⽂件（当然，创建⼀个spring的项⽬就不说了）。对于这个任务，springfox为我们提供了⼀个Docket（摘要的意思）类，我们需要把它做成⼀个Bean注⼊到spring中，显然，我们需要⼀个配置⽂件，并通过⼀种⽅式（显然它会是⼀个注解）告诉程序，这是⼀个Swagger配置⽂件。
⼀个OSA规范⽂档需要许多信息来描述这个API，springfox允许我们将信息组合成⼀个ApiInfo的类，作为构造参数传给Docket（当然也可以不构造这个类，⽽直接使⽤null，但是你的这个API就太low了）。
接下来，我们要写控制器了，当然这不重要，不⽤springfox你依然要写控制器，重要的是要告诉springfox，这个控制器是⼀个需要他来收集API信息的控制器，不⽤说，这依然会采⽤注解的⽅式，同时，我们为了将配置⽂件与控制器结合起来，需要在配置⽂件中指明在什么位置收集可能是API的控制
器的信息。
三、引⼊依赖
如果我写的不错，相信看到这⾥，你就⼤致了解了springfox swagger2的使⽤流程了。那么，我们进⼊正式编码的第⼀步：引⼊依赖。
<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.</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.6</version>
</dependency>
四、⼀个简单的配置⽂件
为了清晰，我们可以先在常⽤的源码包⾥建⼀个config⽬录，并在⾥⾯创建⼀个SwaggerConfig.java⽂件，这是⼀个spring的配置⽂件，所以位置和⽂件名都影响不⼤。
@Configuration //必须存在
@EnableSwagger2 //必须存在
@EnableWebMvc //必须存在
@ComponentScan(basePackages = {"com.ller"}) //必须存在扫描的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("⼩明", "wwwblogs/getupmorning/", "zhaoming0018@126");
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⽂档，需要添加的注解常常很多，若是都写在同⼀个⽂件⾥就会显得臃肿，我们常常会写⼀个接⼝⽂件，将注解都放在接⼝⽂件中，然后再⽤⼀个实体类来实现控制器，算是实现配置和逻辑分离了吧。
六、查看接⼝⽂件和⽂档
Firefox提供了查看JSON的插件，推荐⼤家搜索试试看。
废话不多说，这⾥可以看到之前配置的诸多信息。注⼊description，version，title等。并且确实有TestC
spring framework guruontroller的信息。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。