如何在YAML中表示JSON文档内的JSON Pointer？Swagger场景需求

Got it, let's break down how to handle this Swagger spec scenario where you want to reuse those repeated tree-like nodes using JSON Pointer references. This will keep your spec clean and maintainable instead of duplicating the same node structures everywhere.

Step 1: Define Reusable Node Schemas #

First, you'll want to define each repeated node type (like Organization, Cluster, Plant) as standalone schemas. In OpenAPI 3.x, these go under components.schemas; in Swagger 2.0, they live in definitions.

Step 2: Build the Root Response Structure #

Next, create a top-level schema for your response that references these reusable nodes via JSON Pointer notation (#/components/schemas/[SchemaName] for OpenAPI 3.x, or #/definitions/[SchemaName] for Swagger 2.0).

Full OpenAPI 3.x Example #

{
  "openapi": "3.0.3",
  "info": {
    "title": "Your Resource API",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {
      // Reusable node definitions
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 101
          },
          "name": {
            "type": "string",
            "example": "Org 1"
          }
        },
        "required": ["id", "name"]
      },
      "Cluster": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 201
          },
          "name": {
            "type": "string",
            "example": "Cluster 1"
          }
        },
        "required": ["id", "name"]
      },
      "Plant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 301
          }
          // Add other Plant-specific fields here
        },
        "required": ["id"]
      },
      // Root response structure referencing the nodes
      "ResourceTreeResponse": {
        "type": "object",
        "properties": {
          "organizations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Organization"
            }
          },
          "clusters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Cluster"
            }
          },
          "plants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Plant"
            }
          }
        },
        "required": ["organizations", "clusters", "plants"]
      }
    }
  },
  "paths": {
    "/resources": {
      "get": {
        "summary": "Fetch the full resource tree",
        "responses": {
          "200": {
            "description": "Successfully retrieved the tree structure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceTreeResponse"
                },
                "example": {
                  "organizations": [
                    {"id": 101, "name": "Org 1"},
                    {"id": 102, "name": "Org 2"}
                  ],
                  "clusters": [
                    {"id": 201, "name": "Cluster 1"},
                    {"id": 202, "name": "Cluster 2"}
                  ],
                  "plants": [
                    {"id": 301},
                    {"id": 302}
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Swagger 2.0 Alternative (If You're Using the Older Spec) #

If you're still working with Swagger 2.0, the structure is nearly identical—just swap components.schemas for definitions:

{
  "swagger": "2.0",
  "info": {
    "title": "Your Resource API",
    "version": "1.0.0"
  },
  "definitions": {
    "Organization": {
      "type": "object",
      "properties": {
        "id": {"type": "integer", "example": 101},
        "name": {"type": "string", "example": "Org 1"}
      },
      "required": ["id", "name"]
    },
    "Cluster": {
      "type": "object",
      "properties": {
        "id": {"type": "integer", "example": 201},
        "name": {"type": "string", "example": "Cluster 1"}
      },
      "required": ["id", "name"]
    },
    "Plant": {
      "type": "object",
      "properties": {
        "id": {"type": "integer", "example": 301}
      },
      "required": ["id"]
    },
    "ResourceTreeResponse": {
      "type": "object",
      "properties": {
        "organizations": {
          "type": "array",
          "items": {"$ref": "#/definitions/Organization"}
        },
        "clusters": {
          "type": "array",
          "items": {"$ref": "#/definitions/Cluster"}
        },
        "plants": {
          "type": "array",
          "items": {"$ref": "#/definitions/Plant"}
        }
      },
      "required": ["organizations", "clusters", "plants"]
    }
  },
  "paths": {
    "/resources": {
      "get": {
        "summary": "Fetch the full resource tree",
        "responses": {
          "200": {
            "description": "Success response",
            "schema": {"$ref": "#/definitions/ResourceTreeResponse"},
            "examples": {
              "application/json": {
                "organizations": [{"id":101,"name":"Org 1"}],
                "clusters": [{"id":201,"name":"Cluster 1"}],
                "plants": [{"id":301}]
              }
            }
          }
        }
      }
    }
  }
}

Key Benefits of This Approach #

• No duplication: You only define each node structure once, so updates only need to happen in one place.
• Consistency: All references to Organization, Cluster, etc., will share the exact same schema, avoiding inconsistencies.
• Readability: Your spec stays clean and focused on the overall response structure rather than repeating low-level details.

内容的提问来源于stack exchange，提问作者llasarov