API的全称是应用编程接口(Application Programming Interface) 在互联网时代,把网站的服务封装成一系列计算机易识别的数据接口开放出去,供第三方开发者使用,这种行为就叫做开放网站的API,与之对应的,所开放的API就被称作Open API。
swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者
**优点
Pom文件配置:
Swagger2需要导入两个资源依赖:
#Swagger2资源依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Swagger3只需要导入一个资源依赖:
# Swagger3资源依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Swagger Config配置
package cn.netxiaobao.demo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@EnableOpenApi //开启Swagger3
@Configuration
public class Swagger3 {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30) // v2 不同
.select()
.apis(RequestHandlerSelectors.basePackage("cn.netXiaobao.demo"))//设置扫描路径
.build();
}
}
到此,Swagger配置完毕,启动程序即可
springfox的大致原理就是,在项目启动的过种中,spring上下文在初始化的过程,框架自动跟据配置加载一些swagger相关的bean到当前的上下文中,并自动扫描系统中可能需要生成api文档那些类,并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类,跟据这些Controller类中的方法生成相应的api文档。
如果只用springfox的默认的配置的话,与springmvc集成起来非常简单,只要写一个类似于以下代码的类放到你的项目里就行了,代码如下
@Configuration
@EnableWebMvc
@EnableSwagger2
publicclass ApiConfig {
}
注意到,上面是一个空的java类文件,类名可以随意指定,但必须加入上述类中标出的@Configuration、@EnableWebMvc、@EnableSwagger2三个注解,这样就完成了springmvc与springfox的基本集成,有了三个注解,项目启动后就可以直接用类似于以下的地址来查看api列表了:
http://127.0.0.1:8080/jadDemo/swagger-ui.html
这确实是一个很神奇的效果,简单的三个注解,系统就自动显示出项目里所有Controller类的所有api了。现在,我们就这个配置类入手,简单分析它的原理。这个类中没有任何代码,很显然,三个注解起了至关重要的作用。其中@Configuration注解是spring框架中本身就有的,它是一个被@Component元注解标识的注解,所以有了这个注解后,spring会自动把这个类实例化成一个bean注册到spring上下文中。第二个注解@EnableWebMvc故名思义,就是启用springmvc了,在Eclipse中点到这个注解里面简单看一下,它就是通过元注解@Import(DelegatingWebMvcConfiguration.class)往spring context中塞入了一个DelegatingWebMvcConfiguration类型的bean。我想,这个类的目的应该就是为swagger提供了一些springmvc方面的配置吧。第三个注解:@EnableSwagger2,看名字应该可以想到,是用来集成swagger2的,他通过元注解:@Import({Swagger2DocumentationConfiguration.class}),又引入了一个Swagger2DocumentationConfiguration类型的配置bean,而这个就是Swagger的核心配置了。它里面的代码如下:
@Configuration
@Import({ SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class })
@ComponentScan(basePackages = {
"springfox.documentation.swagger2.readers.parameter",
"springfox.documentation.swagger2.web",
"springfox.documentation.swagger2.mappers"
})
publicclassSwagger2DocumentationConfiguration {
@Bean
public JacksonModuleRegistrar swagger2Module() {
returnnewSwagger2JacksonModule();
}
}
这个类头部通过一些注解,再引入SpringfoxWebMvcConfiguration类和SwaggerCommonConfiguration类,并通过ComponentScan注解,自动扫描springfox .swagger2相关的的bean到spring context中。这里,我最感兴趣的是SpringfoxWebMvcConfiguration这个类,这个类我猜应该就是springfox集成mvc比较核心的配置了,点进去,看到以下代`码:
@Configuration
@Import({ModelsConfiguration.class })
@ComponentScan(basePackages = {
"springfox.documentation.spring.web.scanners",
"springfox.documentation.spring.web.readers.operation",
"springfox.documentation.spring.web.plugins",
"springfox.documentation.spring.web.paths"
})
@EnablePluginRegistries({
DocumentationPlugin.class,
ApiListingBuilderPlugin.class,
OperationBuilderPlugin.class,
ParameterBuilderPlugin.class,
ExpandedParameterBuilderPlugin.class,
ResourceGroupingStrategy.class,
OperationModelsProviderPlugin.class,
DefaultsProviderPlugin.class,
PathDecorator.class
})
publicclassSpringfoxWebMvcConfiguration {
}
这个类中下面的代码,无非就是通过@Bean注解再加入一些新的Bean,我对它的兴趣不是很大,我最感兴趣的是头部通过@EnablePluginRegistries加入的那些东西。springfox是基于spring-plug的机制整合swagger的,spring-plug具体是怎么实现的,我暂时还没有时间去研究spring-plug的原理。但在下文会提到自己写一个plug插件来扩展swagger的功能。上面通过@EnablePluginRegistries加入的plug中,还没有时间去看它全部的代码,目前我看过的代码主要有ApiListingBuilderPlugin.class,OperationBuilderPlugin.class,ParameterBuilderPlugin.class, ExpandedParameterBuilderPlugin.class,
我们把注意点放到上文SpringfoxWebMvcConfiguration这个类代码头部的ComponentScan注解内容上来,这一段注解中扫描了一个叫springfox.documentation.spring.web.plugins的package,这个package在springfox-spring-web-2.6.1.jar中可以找到。这个package下,我们发现有两个非常核心的类,那就是DocumentationPluginsManager和DocumentationPluginsBootstrapper。对于第一个DocumentationPluginsManager,它是一个没有实现任何接口的bean,但它内部有诸多PluginRegistry类型的属性,而且都是通过@Autowired注解把属性值注入进来的。接合它的类名来看,很容易想到,这个就是管理所有plug的一个管理器了。很好理解,因为ComponentScan注解的配置,所有的plug实例都会被spring实例化成一个bean,然后被注入到这个DocumentationPluginsManager实例中被统一管理起来。在这个package中的另一个重要的类DocumentationPluginsBootstrapper,看名字就可以猜到,他可能就是plug的启动类了。点进去看具体时就可以发现,他果然是一个被@Component标识了的组件,而且它的构造方法中注入了刚刚描述的DocumentationPluginsManager实例,而且最关键的,它还实现了SmartLifecycle接口。对spring bean生命周期有所了解的人的都知道,这个组件在被实例化为一个bean纳入srping context中被管理起来的时候,会自动调用它的start()方法。点到start()中看代码时就会发现,它有一行代码scanDocumentation(buildContext(each));就是用来扫描api文档的。进一步跟踪这个方法的代码,就可以发现,这个方法最终会通过它的DocumentationPluginsManager属性把所有plug调起一起扫描整个系统并生成api文档。扫描的结果,缓存在DocumentationCache这个类的一个map属性中。
以上就是,srpingMvc整合springfox的大致原理。它主要是通过EnableSwagger2注解,向spring context注入了一系列bean,并在系统启动的时候自动扫描系统的Controller类,生成相应的api信息并缓存起来。此外,它还注入了一些被@Controller注解标识的Controller类,作为ui模块访问api列表的入口。比如springfox-swagger2-2.6.1.jar包中的Swagger2Controller类。这个Controller就是ui模块中用来访问api列表的界面地址。在访问http://127.0.0.1:8080/jadDemo/swagger-ui.html这个地址查看api列表时,通过浏览器抓包就可以看到,它是通过类似于http://127.0.0.1:8080/jadDemo/v2/api-docs?group=sysGroup这样的地址异步获得api信息(Json格式)并显示到界面上,这个地址后台对应的Controller入口就是上文的Swagger2Controller类,这个类收到请求后,直接从事先初始化好的缓存中的取出api信息生成json字符串返回。
springfox.documentation.swagger.web.ApiResourceController 定义了/swagger-resource相关的API接口来返回我们定义的配置类SwaggerResourcesProvider Controller定义如下:
package springfox.documentation.swagger.web;
@RestController
@ApiIgnore
@RequestMapping({
"${springfox.documentation.swagger-ui.base-url:}/swagger-resources"})
public class ApiResourceController {
@Autowired(required = false)
private SecurityConfiguration securityConfiguration;
@Autowired(required = false)
private UiConfiguration uiConfiguration;
private final SwaggerResourcesProvider swaggerResources;
@Autowired
public ApiResourceController(
SwaggerResourcesProvider swaggerResources,
@Value("${springfox.documentation.swagger-ui.base-url:}") String swaggerUiBaseUrl) {
this.swaggerResources = swaggerResources;
this.uiConfiguration = UiConfigurationBuilder.builder()
.copyOf(uiConfiguration)
.swaggerUiBaseUrl(StringUtils.trimTrailingCharacter(swaggerUiBaseUrl, '/'))
.build();
this.securityConfiguration = SecurityConfigurationBuilder.builder()
.copyOf(securityConfiguration)
.build();
}
@GetMapping(value = "/configuration/security", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<SecurityConfiguration> securityConfiguration() {
return new ResponseEntity<>(securityConfiguration, HttpStatus.OK);
}
@GetMapping(value = "/configuration/ui", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<UiConfiguration> uiConfiguration() {
return new ResponseEntity<>(uiConfiguration, HttpStatus.OK);
}
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<List<SwaggerResource>> swaggerResources() {
return new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK);
}
}
Swagger2Controller中只有一个mapping方法,默认的path值为/v2/api-docs,可以通过配置 springfox.documentation.swagger.v2.path 进行修改。所以默认情况下 /v2/api-docs?group=person-api、/v2/api-docs?group=user-api 这些地址都会被Swagger2Controller所处理。
Swagger2Controller内部获取文档信息会去DocumentationCache中查找:
@RequestMapping(
value = DEFAULT_URL,
method = RequestMethod.GET,
produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE })
@PropertySourcedMapping(
value = "${springfox.documentation.swagger.v2.path}",
propertyKey = "springfox.documentation.swagger.v2.path")
@ResponseBody
public ResponseEntity<Json> getDocumentation(
@RequestParam(value = "group", required = false) String swaggerGroup,
HttpServletRequest servletRequest) {
String groupName = Optional.fromNullable(swaggerGroup).or(Docket.DEFAULT_GROUP_NAME);
Documentation documentation = documentationCache.documentationByGroup(groupName);
if (documentation == null) {
return new ResponseEntity<Json>(HttpStatus.NOT_FOUND);
}
Swagger swagger = mapper.mapDocumentation(documentation);
UriComponents uriComponents = componentsFrom(servletRequest, swagger.getBasePath());
swagger.basePath(Strings.isNullOrEmpty(uriComponents.getPath()) ? "/" : uriComponents.getPath());
if (isNullOrEmpty(swagger.getHost())) {
swagger.host(hostName(uriComponents));
}
return new ResponseEntity<Json>(jsonSerializer.toJson(swagger), HttpStatus.OK);
}
以上就是API解析、扫描的大致处理过程,整理如下:
springfox对文档Documentation的定义
文档Documentation定义得很清晰,主要由groupName(分组名)、basePath(contextPath)、apiListings(API列表集)、resourceListing(资源列表集)等属性组成。
其中API列表被封装成ApiListing。ApiListing中又持有ApiDesciption集合引用,每个ApiDesciption都持有一个API集合的引用,Operation也就是具体的接口操作,内部包含了该接口对应的http方法、produces、consumes、协议、参数集、响应消息集等诸多元素。
springfox通过spring-plugin的方式将Plugin注册到Spring上下文中,然后使用这些plugin进行API的扫描工作,这里的扫描工作其实也就是构造Documentation的工作,把扫描出的结果封装成Documentation并放入到DocumentationCache内存缓存中,之后swagger-ui界面展示的API信息通过Swagger2Controller暴露,Swagger2Controller内部直接从DocumentationCache中寻找Documentation。
下图就是部分Plugin具体构造对应的文档信息:
代码细节方面的分析:
很明显,入口处在@EnableSwagger2注解上,该注解会import一个配置类Swagger2DocumentationConfiguration。
Swagger2DocumentationConfiguration做的事情:
SpringfoxWebMvcConfiguration配置类做的事情跟Swagger2DocumentationConfiguration类似,不过多了一步构造PluginRegistry过程。该过程使用@EnablePluginRegistries注解实现:
@EnablePluginRegistries({ DocumentationPlugin.class,
ApiListingBuilderPlugin.class,
OperationBuilderPlugin.class,
ParameterBuilderPlugin.class,
ExpandedParameterBuilderPlugin.class,
ResourceGroupingStrategy.class,
OperationModelsProviderPlugin.class,
DefaultsProviderPlugin.class,
PathDecorator.class,
ApiListingScannerPlugin.class
})
@EnablePluginRegistries注解是spring-plugin模块提供的一个基于Plugin类型注册PluginRegistry实例到Spring上下文的注解。
@EnablePluginRegistries注解内部使用PluginRegistriesBeanDefinitionRegistrar注册器去获取注解的value属性(类型为Plugin接口的Class数组);然后遍历这个Plugin数组,针对每个Plugin在Spring上下文中注册PluginRegistryFactoryBean,并设置相应的name和属性。
如果处理的Plugin有@Qualifier注解,那么这个要注册的PluginRegistryFactoryBean的name就是@Qualifier注解的value,否则name就是插件名首字母小写+Registry的格式(比如DocumentationPlugin对应构造的bean的name就是documentationPluginRegistry)。
参考: https://blog.csdn.net/qq_25615395/article/details/70229139 https://developer.aliyun.com/article/599809 https://www.jianshu.com/p/9f7af2262b96