集成 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);
}