Integrate SOFARPC RESTful services with Swagger

Use rpc-sofa-boot-starter 6.0.1 or later

Starting from version 6.0.1 of rpc-sofa-boot-starter, SOFARPC provides a one-click integration feature for RESTful services and Swagger. The procedure is as follows:

1. Add the Swagger dependency to the pom.xml file.

   <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. Add com.alipay.sofa.rpc.restSwagger=true to the application.properties file.

3. Access http://localhost:8341/swagger/openapi to retrieve the Swagger OpenAPI content for the SOFARPC RESTful service.

Do not use rpc-sofa-boot-starter or use a version earlier than 6.0.1

If you are not using rpc-sofa-boot-starter or are using a version earlier than 6.0.1, you can integrate Swagger in the following way:

1. Import the Swagger-related dependencies into your application.

   Because the SOFARPC RESTful protocol uses the JAX-RS standard, you only need to import the Swagger dependency for JAX-RS. The dependencies are as follows:

   <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>

   Note

   Import version 20.0 of Guava to resolve version conflicts.

2. Publish a Swagger RESTful service.

   To expose your SOFARPC RESTful services through Swagger OpenAPI, you must create and publish another SOFARPC RESTful service that provides the OpenAPI definitions.

   1. Create a new interface.

      @Path("swagger")
      public interface OpenApiService{
          @GET
          @Path("openapi")
          @Produces("application/json")
          String openApi();
      }

   2. Provide an implementation class and publish it as a SOFARPC RESTful service.

      @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<>();
          // Scan the package of the current class. You can also scan other packages that contain SOFARPC RESTful service interfaces.
          resources.add(this.getClass().getPackage());
          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. After the application starts, access http://localhost:8341/swagger/openapi to retrieve information about all RESTful services published by the current application.

Resolve cross-domain issues

If you use a Swagger UI on a different port to access http://localhost:8341/swagger/openapi to view API definitions and make calls, you may need to resolve cross-domain access issues. To do so, add the following code before the application starts:

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

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