Integration of SOFARPC RESTful and Swagger

From rpc-sofa-boot-starter 6.0.1, you can use SOFARPC to integrate RESTful services and Swagger.

To activate Swagger when rpc-sofa-boot-starter is enabled, first add Swagger dependencies in pom.xml:

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

Then, add com.alipay.sofa.rpc.restSwagger=true in application.properties.

Last, access http://localhost:8341/swagger/openapi to obtain the Swagger OpenAPI of SOFARPC RESTful.

If rpc-sofa-boot-starter is not enabled or the version of rpc-sofa-boot-starter is earlier than 6.0.1, you can integrate Swagger in the following way.

First, introduce Swagger dependencies in the app. You only need to introduce the JAXRS dependency of Swagger because the RESTful protocol of SOFARPC uses the JAXRS standard.

<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 is introduced to avoid version conflicts.

Add a Swagger RESTful service

To enable Swagger to expose the RESTful service of SOFARPC through Swagger OpenAPI, you can provide the OpenAPI service of Swagger through the RESTful service of SOFARPC. First, create an interface:

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

Then, provide an implementation class, and publish it as a RESTful service of SOFARPC:

@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()); // Scan the package where the current class is located, or the package where other RESTful service interfaces of SOFARPC are located.
        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);
            }
        }
    }
}

After the app is started, you can access http://localhost:8341/swagger/openapi to obtain the information about all RESTful services published by the app.

Solve the cross-origin access problem of SOFARPC RESTful service

If you start a Swagger UI on another port and want to access http://localhost:8341/swagger/openapi by using the Swagger UI to view the API definition and initiate a call, you need to solve the cross-origin access problem of the SOFARPC RESTful service by adding the following code before starting the app:

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

In this way, you can use the Swagger UI to access the Swagger OpenAPI provided by the app across domains.