集成 SOFARPC RESTful 服务和 Swagger

本文介绍如何集成SOFARPC RESTful 服务和 Swagger。

使用 rpc-sofa-boot-starter 6.0.1 以上版本

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

  1. pom.xml 中增加 Swagger 的依赖。

    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>20.0</version>
    </dependency>
  2. application.properties 里面增加 com.alipay.sofa.rpc.restSwagger=true

  3. 访问 http://localhost:8341/swagger/openapi 即可获取 SOFARPC 的 RESTful 的 Swagger OpenAPI 内容。

不使用 rpc-sofa-boot-starter 或版本低于 6.0.1

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

  1. 在应用中引入 Swagger 相关的依赖。

    由于 SOFARPC 的 RESTful 协议使用的是 JAXRS 标准,因此只需引入 Swagger 的 JAXRS 依赖。依赖如下:

    <dependency>
          <groupId>io.swagger.core.v3</groupId>
          <artifactId>swagger-jaxrs2</artifactId>
          <version>2.0.0</version>
    </dependency>
    <dependency>
         <groupId>com.google.guava</groupId>
         <artifactId>guava</artifactId>
         <version>20.0</version>
    </dependency>
    说明

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

  2. 发布一个 Swagger 的 RESTful 服务。

    为了让 Swagger 能够将 SOFARPC 的 RESTful 的服务通过 Swagger OpenAPI 暴露出去,可以反向使用 SOFARPC 的 RESTful 的服务提供 Swagger 的 OpenAPI 服务。

    1. 新建一个接口。

      @Path("swagger")
      public interface OpenApiService{
          @GET
          @Path("openapi")
          @Produces("application/json")
          String openApi();
      }
    2. 提供一个实现类,并发布成 SOFARPC 的 RESTful 的服务。

      @Service
      @SofaService(bindings ={@SofaServiceBinding(bindingType ="rest")}, interfaceType =OpenApiService.class)
      public class OpenApiServiceImpl implements OpenApiService,InitializingBean{
           private OpenAPI openAPI;
      
          @Override
          public String openApi(){
               return Json.pretty(openAPI);
          }
      
          @Override
          public void afterPropertiesSet(){
          List<Package> resources =new ArrayList<>();
          resources.add(this.getClass().getPackage());// 扫描当前类所在的 Package,也可以扫描其他的 SOFARPC RESTful 服务接口所在的 Package
          if(!resources.isEmpty()){
               // init context
              try{
                  SwaggerConfiguration oasConfig =new SwaggerConfiguration()
                  .resourcePackages(resources.stream().map(Package::getName).collect(Collectors.toSet()));
      
                  OpenApiContext oac =new JaxrsOpenApiContextBuilder()
                  .openApiConfiguration(oasConfig)
                  .buildContext(true);
                  openAPI = oac.read();
              }catch(OpenApiConfigurationException e){
                 throw new RuntimeException(e.getMessage(), e);
             }
          }
        }
      }
  3. 应用启动后,访问 http://localhost:8341/swagger/openapi 即可得到当前的应用发布的所有的 RESTful 的服务的信息。

解决跨域问题

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

import org.jboss.resteasy.plugins.interceptors.CorsFilter;

public static void main(String[] args){
    CorsFilter corsFilter =newCorsFilter();
    corsFilter.getAllowedOrigins().add("*");
    JAXRSProviderManager.registerCustomProviderInstance(corsFilter);
    SpringApplication.run(DemoApplication.class, args);
}