1

我正在定义要实现的 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 指针？

4

2 回答 2

2

首先，你为什么不直接包含数据？在实际的 API 响应中使用 JSON 引用/JSON 指针是一个非常不常用的场景，它需要您的 API 客户端使用 JSON 引用解析库来计算这些引用。大多数语言/框架都有 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'
于 2018-03-19T12:56:35.597 回答
1

YAML 提供了anchors 和 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
于 2018-03-19T12:01:18.053 回答