开发者或多或少都被接口文档折磨过，经常会遇到接口文档与实际的情况不符，而接口开发人员又觉得编写及维护接口文档会耗费不少精力，经常来不及更新，所以无论是接口使用者或开发者都希望能有一个好的接口文档。而Swagger就是解决这一痛点的解决方案，也是很多开发者都接触过的一个方案。Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。
那Swagger是如何实现这些功能的呢？这篇文章将介绍SpringBoot基于swagger-jersey2-jaxrs实现的Swagger，而不是Spring MVC。
源码解析
在SpringBoot启动的时候会添加注解来启动和配置Swagger，如下的例子
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
@Primary
public SwaggerResourcesProvider getSwaggerResourcesProvider() {
return () -> {
SwaggerResource jerseySwaggerResource = new SwaggerResource();
jerseySwaggerResource.setLocation("/api/swagger.json");
jerseySwaggerResource.setSwaggerVersion("3.0");
jerseySwaggerResource.setName("PatchConfig");
return Collections.singletonList(jerseySwaggerResource);
};
}
}
配置接口扫描路径
@Configuration
@ApplicationPath("/api")
public class PatchCfgResourceConfig extends ResourceConfig {
private final Feature jerseyOperationalFeature;
@Inject
public PatchCfgResourceConfig(@Named("jersey-operational-feature") Feature jerseyOperationalFeature){
this.jerseyOperationalFeature = jerseyOperationalFeature;
}
@PostConstruct
public void init() {
register(XXXCfgResource.class);
register(JobResource.class);
register(PatchCfgResource.class);
configSwagger();
}
private void configSwagger() {
this.register(ApiListingResource.class);
this.register(SwaggerSerializers.class);
BeanConfig config = new BeanConfig();
config.setConfigId("patch-config");
config.setTitle("Patch Config REST API");
config.setVersion("v1");
config.setSchemes(new String[]{"http", "https"});
config.setBasePath("/api");
config.setResourcePackage("com.sample.resources");
config.setPrettyPrint(true);
config.setScan(true);
}
}
io.swagger.jaxrs.config.BeanConfig.setScan(true)方法会直接启动swagger去扫描相关的class，比如Path, SwaggerDefinition, Api等等，追踪代码后，会看到调用classes方法。
classes方法
在SpringBoot应用程序启动后，我们可以访问/swager-ui.html查看swagger的UI页面，会有相关的接口和文档信息
Swagger UI例子
这时我们打开浏览器开发者工具查看网络调用可以发现几个关键的http访问
image.png
/swagger-resource 的返回信息如下，这些其实就是上面配置过的信息
swagger-resource
springfox.documentation.swagger.web.ApiResourceController 定义了/swagger-resource相关的API接口来返回我们定义的配置类SwaggerResourcesProvider
ApiResourceController
第二个前端UI请求的接口为/api/swagger.json，这个也是上面配置过的url，这个API则由io.swagger.jaxrs.listing.ApiListingResource来处理
swagger.json
返回的信息如下
swagger.json
在ApiResourceController中有一个方法getListingJsonResponse，跟踪下去可以看到scan方法
scan
在上面我们配置过的io.swagger.jaxrs.config.BeanConfig是实现Scanner接口的，在启动时会调用classes，而这里也调用的classes，此时就会返回SpringBoot应用配置过的API接口信息给前端UI了。这就是Swagger在SpringBoot中从启动到UI展示接口信息的流程和原理了。
网友评论