JSON Pointer inside JSON 文件：如何用YAML表达？

Question

我正在定义要实施的 REST 服务的 Swagger 规范。由于响应文档表示一个树状结构，其中几个节点重复多次，我想在文档的开头定义它们，然后通过 JSON 指针表示法引用它们。

因此响应文档应如下所示：

{
    "definitions": {
        "organizations": [
            { "id": 101, "name": "Org 1" },
            ...
        ],        
        "clusters": [
            { "id": 201, "name": "Cluster 1" },
            ...
        ],        
        "plants": [
            { "id": 301 }
        ]
    },    
    "plants_hierarchy": {
        "relations": [
            {
                "cluster": { "$ref", "#/definitions/clusters/1" },
                "organization": { "$ref", "#/definitions/organizations/123" },                    
                "plants": [
                    { "$ref": "#/definitions/plants/234" },
                    ...
                ]
            },
            ...
        ]
    }
}

#/plants_hierarchy/relations/plants 中的植物对象应表示为 JSON 指针而不是原始对象，以保持文档较小。

我的问题是如何在Swagger YAML文档中表达JSON指针？

Answer 1

YAML 提供 anchors and aliases，它完全涵盖了您的 use-case：

definitions:
  organizations:
    - &my_organization
      id: 101
      name: Org 1
  clusters:
    - &my_cluster
      id: 201
      name: Cluster 1
  plants:
     - &my_plant
       id: 301 
plants_hierarchy:
  relations:
    - cluster: *my_cluster
      organization: *my_organization
      plants:
        - *my_plant

Answer 2

首先，你为什么不直接包含内联数据？在实际 API 响应中使用 JSON References/JSON 指针是一种相当不常见的情况，它需要您的 API 客户端使用 JSON 参考解析库来计算那些参考资料。大多数 languages/frameworks 有 JSON 库，但 JSON 参考解析库很少见。如果所有数据都是内联的，那么访问它就很简单了——例如只需使用 response.plants_hierarchy.relations[0].cluster.name。但是将数据隐藏在 JSON 引用之后会使客户的事情变得更加复杂。

无论如何，如果你确定这是你想要做的，那么 $ref 属性可以定义一个简单的 string 属性，可能带有pattern.

swagger: '2.0'
...

definitions:
  JsonReference:
    type: object
    properties:
      '$ref':
        type: string
        pattern: '^#'
        example: '#/definitions/something/1'

  Relation:
    type: object
    properties:
      cluster:
        $ref: '#/definitions/JsonReference'
      organization:
        $ref: '#/definitions/JsonReference'
      plants:
        type: array
        items:
          $ref: '#/definitions/JsonReference'

JSON Pointer inside JSON 文件：如何用YAML表达？

JSON Pointer inside JSON document: how to express in YAML?

json

yaml

swagger

jsonpointer