using swagger

使用框架Swagger生成契约

为满足开发需要，Spring Cloud Huawei提供接口契约生成组件，目前只支持Servicecomb引擎契约展示，默认上限为100个，pom依赖如下：

<dependency>
  <groupId>com.huaweicloud</groupId>
  <artifactId>spring-cloud-starter-huawei-swagger</artifactId>
</dependency>

默认spring-cloud-starter-huawei-service-engine组件已经包含了swagger依赖，如果由于契约个数受限无法注册，可以剔除swagger依赖正常注册。

版本差异

2022.0.x/2023.0.x分支目前仅支持Springdoc构建契约信息；

2021.0.x分支支持Springdoc及Servicecomb构建契约信息，1.11.8-2021.0.x及以下版本默认使用Servicecomb构建契约，1.11.9-2021.0.x及之后版本默认使用Spring DOC构建契约；

2020.0.x及其他分支支持Springfox及Servicecomb构建契约信息，默认使用Servicecomb构建契约；

是否使用Servicecomb构建契约可以通过spring.cloud.servicecomb.swagger.enableJavaChassisAdapter配置调整。

契约生成限制

• Springdoc

Springdoc实现逻辑中并未考虑@Scope注解作用域问题，而Spring Cloud Huawei是在微服务注册的时候生成的契约，如果接口类中存在注册@Scope("request")或者@Scope("session")时会导致契约生成异常。

1、不支持@Scope("request")或者@Scope("session")生成契约

@RestController
@RefreshScope
//@Scope("request")
@Scope("session")
public class ProviderController {}

2、支持接口定义mapping映射,正常生成契约。

public interface ProviderControllerInterface {
  @GetMapping("testInterfaceMapping")
  String testInterfaceMapping();
}

@RestController
public class ProviderController implements ProviderControllerInterface{
  @Override
  public String testInterfaceMapping() {
    return "Hello";
  }
}

3、Springdoc集成swaggerV3的api，所以接口中的描述注解需要使用V3对应的注解，V2注解在契约生成时无法生效。

• Servicecomb

1、2021.0.x分支在1.11.9-2021.0.x及之后版本当接口类中存在@Scope("request")或者@Scope("session")注解时，忽略该注解的类生成契约，不报异常，其他版本生成契约时异常。

2、接口定义mapping映射时，生成的契约将无法获取mapping映射关系。

3、Springdoc集成swaggerV2的api，所以接口中的描述注解需要使用V2对应的注解，V3注解在契约生成时无法生效。

SwaggerV2与V3常用注解对应关系

SwaggerV2(spirngfox或servicecomb)注解	SwaggerV3(spirngdoc)注解
@Api	@Tag
@ApiIgnore	@Hidden or @Parameter(hidden=true) or @Operation(hidden=true)
@ApiImplicitParam	@Parameter
@ApiImplicitParams	@Parameters
@ApiModel	@Schema
@ApiModelProperty(hidden=true)	@Schema(accessMode=READ_ONLY)
@ApiModelProperty	@Schema
@ApiOperation(value="foo",notes="bar",nickname="sayHello")	@Operation(summary="foo",description="bar",operationId="sayHello")
@ApiParam	@Parameter
@ApiResponse(code=404,message="foo")	@ApiResponse(responseCode="404",description="foo")