faq swagger register

服务注册契约

契约是微服务的接口描述，OpenAPI定义了接口描述的标准。Spring Cloud Huawei在应用启动的时候， 会根据@RestController的定义，生成OpenAPI并将信息注册到注册中心。

在微服务架构下，所有服务都通过网络接口相互访问，接口管理是非常重要的功能。注册契约是实现 接口管理的入门级功能。

说明：在Spring Cloud Huawei 1.10.5及其以上版本，默认会覆盖契约，不会碰到本文提到的问题，本文的问题只适用于老版本。

Spring Cloud Huawei契约注册的约束

契约是接口描述，微服务在开发的过程中，每个版本接口都可能发生变化。为了保证看到每个版本的契约， 微服务定义了版本号:

spring:
  cloud:
    servicecomb:
      discovery:
        version: 0.0.1

当接口变化的时候，如果版本号没有修改，那么微服务注册会失败。启动日志通常会有如下错误输出：

Service has already registered, but schema ids not equal, stop register. 
Change the microservice version or delete the old microservice info and try again.

处理契约的最佳实践

在开发过程中，如果接口需要频繁修改，那么每次修改版本号也是非常麻烦的。可以采取下面的任意方式 来解决服务启动失败的问题：

• 方案一

  在注册中心删除微服务信息，然后重新启动微服务。

• 方案二

  在bootstrap.yaml中增加如下配置项忽略注册失败：

    ```
    spring:
      cloud:
        servicecomb:
          discovery:
            ignoreSwaggerDifferent: true
    ```
  

• 方案三

  在使用ServiceStage部署微服务的情况下，可以考虑将ServiceStage的组件版本号作为微服务的版本号。ServiceStage版本号在每次重新部署的时候，都需要更新，使用该版本号避免了开发阶段需要修改版本号的麻烦。使用ServiceStage部署，建议bootstrap.yml采用如下配置文件模板：

  spring:
    application:
      # 微服务名称，本示例使用ServiceStage组件名称，建议修改为固定值，因为微服务名称会被客户端使用，不能轻易变化。
      name: ${CAS_COMPONENT_NAME}
    cloud:
      servicecomb:
        discovery:
          # 应用名称，本示例使用ServiceStage组件名称，建议修改为固定值，因为只有应用名称相同的微服务才能够相互发现，不能轻易变化。
          appName: ${CAS_APPLICATION_NAME:default-application}
          serviceName: ${spring.application.name}
          # 注册中心地址，本示例使用ServiceStage环境变量。建议保留这种配置方式，部署的时候，不用手工修改地址。
          address: ${PAAS_CSE_SC_ENDPOINT:http://127.0.0.1:30100}
          # 微服务版本号，本示例使用ServiceStage环境变量。建议保留这种配置方式，部署的时候，不用手工修改版本号，防止契约注册失败。
          version: ${CAS_INSTANCE_VERSION:0.0.1}
        config:
          # 配置中心地址，本示例使用ServiceStage环境变量。建议保留这种配置方式，部署的时候，不用手工修改地址。
          serverAddr: ${PAAS_CSE_CC_ENDPOINT:http://127.0.0.1:30110}
          serverType: kie