swagger客户端中的对象图

Question

情况

我正在为现有代码库制定OpenAPI v3规范。该方法基于jaxrs（球衣）上下文中的swagger-core。 API将需要支持由顶点（具有属性的实体）和边线（链接可能具有属性的顶点）组成的图形。对于json（反）序列化，我们依赖杰克逊。

模型（与图形有关）类似于：

Vertex:
  type: object
  ...
  properties:
    id:
      type: string
    ...

Edge:
  type: object
  ...
  properties:
    start:
      $ref: '#/components/schemas/Vertex'
    destination:
      $ref: '#/components/schemas/Vertex'

问题/挑战

有两个问题：

• 开销：此架构（以及我们的使用方式）将导致顶点在边的起始和目标字段中重复。这是不必要的有效负载，对于较大的顶点（可能是属性/较大的值）和许多引用这些顶点的边来说可能是相当大的。
• 正确性：一个更严重的问题是，可能不清楚哪个顶点是正确的顶点。即请求/响应中可能会有多个具有相同ID但值不同的Vertex实例。这似乎容易出错。

解决方案的方向

在API方面，我们可以使用@JsonIdentityInfo和@JsonIdentityReference解决这些问题。但是，似乎无法生成与此相关的客户端。

我想这里的主要问题是缺乏OpenAPI规范/ JSON模式对对象引用的支持。

在我的“ Google努力”中，OAS / JSON模式本身中的引用周围的内容使很多领域感到困惑。

我一直在研究JSON Reference和Javascript Object Graph，但是我没有发现将这些想法整合到OAS模式中的钩子。

模型参考字符串

对我而言，最可能采用的方法是将Edge的开始和目标属性建模为string s。至少可以解决上述问题。这确实带来了一个新问题：由摇摇欲坠生成的客户端使用起来不太直观：

new Edge()
   .start(vertexA.getId())
   .destination(vertexB.getId())
代替

new Edge()
   .start(vertexA)
   .destination(vertexB)
即使阅读回复，问题也更加严重：

Vertex start = graph.getVertices().stream()
     .filter(v -> v.getId().equals(edge.getStart()))
     .findFirst();
Vertex destination = graph.getVertices().stream()
     .filter(v -> v.getId().equals(edge.getDestination()))
     .findFirst();
代替

Vertex start = edge.getStart();
Vertex destination = edge.getDestination();
更糟糕的是，API将同时具有Vertex和Edge的类层次结构。当将string用作开始和目标属性的类型时，客户端中的类型安全性将变得毫无用处。

帮助

[有人在这种模式上有经验吗？关于如何在客户端生成器中对模式和/或支持进行建模的任何建议？

情况我正在研究现有代码库的OpenAPI v3规范。该方法基于jaxrs（球衣）上下文中的swagger-core。 API将需要支持由...

Answer 1

我的经历完全一样，尤其是关于Google搜索：有很多JSON模式参考命中，它们都与复杂的对象图序列化无关。