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完全涵盖了您的用例：

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引用/ JSON指针是一个相当不寻常的场景，它需要您的API客户端使用JSON参考解析库来计算这些引用。大多数语言/框架都有JSON库，但JSON Reference解析库很少见。如果所有数据都是内联的，那么访问它是微不足道的 - 例如只需使用response.plants_hierarchy.relations[0].cluster.name即可。但是隐藏JSON References背后的数据会让客户的事情变得更加复杂。

无论如何，如果您确定这是您想要做的，那么$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文档中的JSON指针：如何在YAML中表达？

2 个答案: