全部产品
云市场

集成 SOFARPC RESTful 服务和 Swagger

更新时间:2020-02-18 09:25:00

rpc-sofa-boot-starter 6.0.1 版本开始,SOFARPC 提供了 RESTful 服务和 Swagger 的一键集成的能力。

在使用了 rpc-sofa-boot-starter 的情况下,如果想要开启 swagger 的能力,首先需要在 pom.xml 中增加 Swagger 的依赖:

  1. <dependency>
  2. <groupId>io.swagger.core.v3</groupId>
  3. <artifactId>swagger-jaxrs2</artifactId>
  4. <version>2.0.0</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.google.guava</groupId>
  8. <artifactId>guava</artifactId>
  9. <version>20.0</version>
  10. </dependency>

然后在 application.properties 里面增加 com.alipay.sofa.rpc.restSwagger=true

最后,访问 http://localhost:8341/swagger/openapi 就可以拿到 SOFARPC 的 RESTful 的 Swagger OpenAPI 内容。

如果没有使用 rpc-sofa-boot-starter 或者在 rpc-sofa-boot-starter 的版本低于 6.0.1,可以采用如下的方式集成 Swagger。

首先,需要在应用中引入 Swagger 相关的依赖,由于 SOFARPC 的 RESTful 协议s使用的是 JAXRS 标准,因此只需引入 Swagger 的 JAXRS 依赖即可。

  1. <dependency>
  2. <groupId>io.swagger.core.v3</groupId>
  3. <artifactId>swagger-jaxrs2</artifactId>
  4. <version>2.0.0</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.google.guava</groupId>
  8. <artifactId>guava</artifactId>
  9. <version>20.0</version>
  10. </dependency>

上面引入 Guava 的 20.0 的版本是为了解决 Guava 的版本冲突。

增加一个 Swagger 的 RESTful 服务

为了能够让 Swagger 将 SOFARPC 的 RESTful 的服务通过 Swagger OpenAPI 暴露出去,可以反过来用 SOFARPC 的 RESTful 的服务提供 Swagger 的 OpenAPI 服务。首先,需要新建一个接口:

  1. @Path("swagger")
  2. public interface OpenApiService {
  3. @GET
  4. @Path("openapi")
  5. @Produces("application/json")
  6. String openApi();
  7. }

然后提供一个实现类,并且发布成 SOFARPC 的 RESTful 的服务:

  1. @Service
  2. @SofaService(bindings = {@SofaServiceBinding(bindingType = "rest")}, interfaceType = OpenApiService.class)
  3. public class OpenApiServiceImpl implements OpenApiService, InitializingBean {
  4. private OpenAPI openAPI;
  5. @Override
  6. public String openApi() {
  7. return Json.pretty(openAPI);
  8. }
  9. @Override
  10. public void afterPropertiesSet() {
  11. List<Package> resources = new ArrayList<>();
  12. resources.add(this.getClass().getPackage()); // 扫描当前类所在的 Package,也可以扫描其他的 SOFARPC RESTful 服务接口所在的 Package
  13. if (!resources.isEmpty()) {
  14. // init context
  15. try {
  16. SwaggerConfiguration oasConfig = new SwaggerConfiguration()
  17. .resourcePackages(resources.stream().map(Package::getName).collect(Collectors.toSet()));
  18. OpenApiContext oac = new JaxrsOpenApiContextBuilder()
  19. .openApiConfiguration(oasConfig)
  20. .buildContext(true);
  21. openAPI = oac.read();
  22. } catch (OpenApiConfigurationException e) {
  23. throw new RuntimeException(e.getMessage(), e);
  24. }
  25. }
  26. }
  27. }

这样,应用启动后,访问 http://localhost:8341/swagger/openapi 即可得到当前的应用发布的所有的 RESTful 的服务的信息。

解决跨域问题

如果用户在另外一个端口中启动了一个 Swagger UI,并且希望通过 Swagger UI 来访问 http://localhost:8341/swagger/openapi 查看 API 定义,发起调用,那么可能需要解决访问跨域的问题,要解决 SOFARPC RESTful 服务访问跨域的问题,可以在应用启动前增加如下的代码:

  1. import org.jboss.resteasy.plugins.interceptors.CorsFilter;
  2. public static void main(String[] args) {
  3. CorsFilter corsFilter = new CorsFilter();
  4. corsFilter.getAllowedOrigins().add("*");
  5. JAXRSProviderManager.registerCustomProviderInstance(corsFilter);
  6. SpringApplication.run(DemoApplication.class, args);
  7. }

这样,Swagger UI 就可以跨域访问应用提供的 Swagger OpenAPI 了。