servicecomb-java-chassis

servicecomb-java-chassis copied to clipboard

问题场景

同一个REST接口类中有类名相同而包名不同的两个参数类型, 生成的契约在definitions字段里只会呈现其中一个类的信息.

根因Swagger对象的definitions参数是一个LinkedHashMap类型. 而对于 Java 对象类型的参数, Java-Chassis是依赖Swagger的工具类生成io.swagger.models.ModelImpl模型信息的, 根据ModelImpl#getName作为key保存到definitions map中. 这里的ModelImpl#getName默认返回的是参数类型的简单类名, 因此同名不同包的类在这个definitions map中相互覆盖, 最终只有一个类型的信息留在 definitions 里面.

规避手段

在参数类型信息上可以打上io.swagger.annotations.ApiModel注解, 如

@ApiModel(value = "personAnother")
public class Person {
  // ...
}

可以覆盖ModelImpl#getName的返回值, 让definitions中的类型信息区分开来. 但不足之处在于, 一方面此问题比较隐晦, 启动阶段不会报错, 在运行时出了问题业务才能察觉. 二来对业务的代码有一定的要求, 如果参数类型来自一个公共包, 可能业务无法在上面打注解.

建议和诉求

最好的结果是 Java-Chassis 优化一下契约生成逻辑, 用全限定类名之类的做io.swagger.models.Swagger#definitions 的 key. 如果实在做不到, 最好也要实现一个查重逻辑, 一旦遇到这种问题场景立即报错, 让业务感知, 不能带病上线.

Java-Chassis 1.5.0 分支麻烦也带一下这个优化项, 多谢了~

目前没有很好的优化手段

3.0.0的行为：

如果两个Model同名，但是对应的swagger相同， 不报错。 比如：

package org.apache.servicecomb.swagger.generator.springmvc.model.same1;

public class SameModel {
  private String name;
}

package org.apache.servicecomb.swagger.generator.springmvc.model.same2;

public class SameModel {
  private String name;
}

如果两个Model同名，但是对应的swagger不同， 报错。 比如：

package org.apache.servicecomb.swagger.generator.springmvc.model.same1;

public class SameModel {
  private String name;
  private int age; // diffrent.
}

package org.apache.servicecomb.swagger.generator.springmvc.model.same2;

public class SameModel {
  private String name;
}

2.8.x上述两种情况钧抛出异常。 3.0.0统一修改为抛出异常。 1.3.x 不处理， 本单关闭。