Swagger 中的 $ref 标签

Posted 2023-02-19

【中文标题】Swagger 中的 $ref 标签

【英文标题】：$ref tag in Swagger

【发布时间】：2016-02-08 06:25:23

【问题描述】：

如何在 Swagger 中使用 $ref 标签来引用不同文件中的定义？

Swagger Editor 中的所有示例都定义了 same 文件中 $ref 标记所引用的任何内容。

例如在 Swagger Editor 上可用的 Uber API 示例中，它有许多引用，例如“#/definitions/Product”和“#/definitions/Errors”。但是，两者都在“定义”部分的 same 文件中定义。

如果我想在一个不同的文件中定义“产品”或“错误”，我该怎么做呢？定义文件将包含哪些标签？它是否需要 Swagger 的所有强制标志（如 paths）？另外，如何在文档中呈现定义？

【参考方案1】：

这是一个例子：

"parameters": [
 
    "name": "cat",
    "in": "body",
    "description": "The JSON payload for the new cat",
    "required": true,
    "schema": 
       "$ref": "cat-new.json"
    
  
]

并且 cat-new.json 定义了以下内容：

  "description":"An adorable cat",
  "type":"object",
  "properties":
    "name":
       "type":"string",
       "description":"The name given to this cat by the adoption staff",
       "minLength":3,
       "maxLength":15
    ,
    "colour":
       "type":"string",
       "description":"The colour of the cat's fur",
       "enum":[
          "black",
          "tan",
          "ginger",
          "blue",
          "white"
       ]
    ,
    "toys":
       "type":"array",
       "description":"The favourite toys of the cat",
       "items":
          "type":"string"
       ,
       "maxItems":3,
       "uniqueItems":true
    
  

参考：

1) https://github.com/swagger-api/swagger-codegen/issues/1145

2)https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#relative-schema-file-example

【讨论】：

谢谢@wing328。我现在了解如何引用定义文件。我假设我需要将它放在与主文件相同的文件夹中。 Swagger 编辑器/任何 Swagger 文档门户会从本地驱动器读取它并将其显示在定义中吗？

我不确定 swagger-editor 如何处理 $ref 到本地文件或 URL。请在github.com/swagger-api/swagger-editor/issues 打开一个“问题”以了解更多信息。