本文介绍如何集成SOFARPC RESTful 服务和 Swagger。
使用 rpc-sofa-boot-starter 6.0.1 以上版本
从 rpc-sofa-boot-starter
6.0.1 版本开始,SOFARPC 提供了 RESTful 服务和 Swagger 的一键集成能力。操作步骤如下:
在
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>
在
application.properties
里面增加com.alipay.sofa.rpc.restSwagger=true
。访问
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:
在应用中引入 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 的版本冲突。
发布一个 Swagger 的 RESTful 服务。
为了让 Swagger 能够将 SOFARPC 的 RESTful 的服务通过 Swagger OpenAPI 暴露出去,可以反向使用 SOFARPC 的 RESTful 的服务提供 Swagger 的 OpenAPI 服务。
新建一个接口。
@Path("swagger") public interface OpenApiService{ @GET @Path("openapi") @Produces("application/json") String openApi(); }
提供一个实现类,并发布成 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); } } } }
应用启动后,访问
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);
}