【自动生成接口文档】Sofaboot集成Swagger3并通过Yapi做接口管理

Sofaboot和Swagger

sofaboot支持swagger3的标准，而且sofa stack官方文档有如何集成swagger的教程：

两种集成方式：

第一种：使用 rpc-sofa-boot-starter 且版本不低于 6.0.1

<dependency>
     <groupId>com.alipay.sofa</groupId>
     <artifactId>rpc-sofa-boot-starter</artifactId>
     <version>6.0.1</version>
</dependency> 

在使用了 rpc-sofa-boot-starter 的情况下，如果想要开启 swagger 的能力，
首先需要在 pom.xml 中增加 Swagger 的依赖

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.0.0</version>
</dependency>

然后在 application.properties 里面增加：

spring.application.name = demo
com.alipay.sofa.rpc.restSwagger=true

最后，访问 http://localhost:8341/swagger/openapi 就可以拿到 SOFARPC 的
 RESTful 的 Swagger OpenAPI 内容

第二种：引入 Swagger 相关的依赖

需要在应用中引入 Swagger 相关的依赖，由于 SOFARPC 的 
RESTful 协议走的是 JAXRS 标准，因此我们引入 Swagger 的 JAXRS 依赖即可

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.0.0</version>
</dependency>

为了能够让 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 的服务的信息。

集成 SOFARPC RESTful 服务和 Swagger的官方链接

添加依赖

        <dependency>
            <groupId>com.alipay.sofa</groupId>
            <artifactId>rpc-sofa-boot-starter</artifactId>
            <version>6.0.1</version>
        </dependency>

        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2</artifactId>
            <version>2.0.0</version>
        </dependency>

application.yaml添加配置

com:
  alipay:
    sofa:
      rpc:
        restSwagger: true #启用Swagger

定义接口

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Tag(name = "测试接口管理-SofaBootSwagger3")
@Path("/test")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface TestFacade {

    @Operation(summary = "测试接口")
    @Path("/getCarInfo")
    @POST
    CarInfoResponseDTO test(CarInfoRequestDTO carInfoRequestDTO);
}

实现接口

import com.alipay.sofa.runtime.api.annotation.SofaService;
import com.alipay.sofa.runtime.api.annotation.SofaServiceBinding;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Slf4j
@Service
@SofaService(interfaceType = TestFacade.class, bindings = {
        @SofaServiceBinding(bindingType = "rest")})
public class TestFacadeImpl implements TestFacade {

    @Override
    public CarInfoResponseDTO test(CarInfoRequestDTO carInfoRequestDTO) {
        return null;
    }
}

入参添加注解

import io.swagger.v3.oas.annotations.media.Schema;

import java.io.Serializable;

 @Data
@Schema(name = "CarInfoRequestDTO", description = "车辆信息DTO")
public class CarInfoRequestDTO implements Serializable {

    @Schema(name = "vin", description = "车架号", required = true)
    private String vin;

    @Schema(name = "plateNo", description = "车牌号", required = true)
    private String plateNo;

    @Schema(name = "plateType", description = "号牌种类", required = true)
    private String plateType;

    @Schema(name = "vehicleName", description = "厂牌型号", required = true)
    private String vehicleName;

    @Schema(name = "orderId", description = "订单id", required = true)
    private String orderId;
 }

返参添加注解

@Schema(name = "CarInfoResponseDTO", description = "车辆信息响应DTO")
public class CarInfoResponseDTO {

    @Schema(name = "vin", description = "车架码(vin码)", required = true)
    private String vin;

    @Schema(name = "plateNo", description = "车牌号", required = true)
    private String plateNo;

    @Schema(name = "engNO", description = "发动机号", required = true)
    private String engNO;
 }

启动项目后,访问地址 http://localhost:8341/swagger/openapi

配置YAPi

配置生效

接口信息

接口入参和返参

相关链接

OpenApi和Swagger2 Swagger3的关系
Springboot集成Swagger2并通过Yapi做接口管理
Springboot集成OpenAPI-Swagger3并通过Yapi做接口管理
Springboot集成springFox-Swagger3并通过Yapi做接口管理

swagger-yapi-demo项目下载