在远程服务器上托管可重用组件定义，并在开放式API规范3.0中将它们用作$ ref

Question

我正在尝试在OAS 3.0（OpenAPI规范3.0）中创建可重用组件定义并由$ref引用它们时进行POC。我在下面尝试过：

1. 在我的本地计算机上下载了Swagger编辑器。
2. 在本地计算机上创建一个文件，该文件包含一个我们希望在多个API之间重用的常见响应。
3. 在规范中提供该文件的引用-"$ref": "file:///path of local directory/myreference.json"

输出未反映我引用的文件的内容。我在这里做错什么了吗？

还想知道是否假设我们在GitHub等回购协议上托管此类规范，那么它们是否可以正确解析引用，并且可以由某些CMS系统提取以呈现UI？

感谢有关此问题的所有提示。

Answer 1

Hej Santosh，

OpenAPI不支持区域设置文件系统引用的绝对路径。来自documention over at swagger.io 您会看到，对于您的情况，您想尝试使用位于另一个文件夹中的文档元素方案的 Remote Reference 方法，并使用规范位置的相对路径：< / p>

  

  
• 本地参考 – Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click 'get the details of the item Dim R As POS.POSDS.ItemsRow = CType(Button1.Tag, POSDS.ItemsRow) 'next search for the barcode in the DGV Dim I As Integer Dim ItemLoc As Integer = -1 For I = 0 To DGV2.Rows.Count - 1 If R.Barcode Is DGV2.Rows(I).Cells(0).Value Then ' Problem: R.Barcode Is DGV2.Rows ItemLoc = I Exit For End If Next End Sub $ref: '#/definitions/myElement'表示转到当前文档的根目录，然后依次查找元素定义和myElement。
  
• 远程参考 – #使用位于同一服务器上同一位置的整个文档。      
    
  • 位于同一服务器上的文档元素 – $ref: 'document.json'
    
  • 位于父文件夹中的文档元素 – $ref: 'document.json#/myElement'
    
  • 文档元素位于另一个文件夹中 – $ref: '../document.json#/myElement'
    
  
• URL参考 – $ref: '../another-folder/document.json#/myElement'使用位于不同服务器上的整个文档。      
    
  • 存储在不同服务器上的文档的特定元素– $ ref：'http://path/to/your/resource.json#myElement'   使用相同协议（例如，HTTP或HTTPS）的不同服务器上的文档– $ ref：'//anotherserver.com/files/example.json'
    
  

Answer 2

尽管$ref: file:///path是有效的JSON引用 ^[1] ，但是您不应使用它们，因为它们不可移植。相反，请使用lordrhodos's answer中建议的相对引用，例如$ref: '../relative/path/to/file.yaml'或类似内容。

$ref: file:///...在Swagger UI和Swagger编辑器中不起作用的原因是它们是网页，并且使用JavaScript解析定义，并且浏览器拒绝从JavaScript访问file:///方案安全原因。

  

您能推荐一个可用于托管可重复使用的定义文件的网站吗？

SwaggerHub为OpenAPI定义提供云托管。可重用的组件（模式定义，响应等）可以存储在所谓的“域”文件中，并可以在多个API定义中使用。

披露：我为SwaggerHub的公司工作

---

^[1] _{根据JSON Reference Specification：}

  

_{“ $ ref”字符串值包含URI [RFC3986]，}

_{和file:///...是有效的URI。}