yaml - 在 API 管理前端中保存 Swagger 文档时缺少架构

Question

这是我在尝试将前端 Swagger 文档添加到我们的团队 API 中时遇到的问题。

在我原来的 Swagger 文档(Swagger 2.0)中，我在提到的响应正文路径下有一个字段:

  responses:
    '200':
      description: Success
      schema:
        $ref: '#/definitions/QueryResponse'
    '401':
      $ref: '#/responses/401'
    '403':
      $ref: '#/responses/403'

但是，当我使用 OpenAPI 编辑器保存 API 管理前端中的文档时，我发现响应中的 $ref 全部消失了，文档自动更改为以下内容:

  responses:
    '200':
      description: Success
    '401':
      description: Unauthorized (ensure correct authorization header in the request)
    '403':
      description: >-
        Forbidden to perform the operation (ensure the client has correct
        role for the partition Id)

不仅 401 和 403 的 $ref 变成直接从响应对象中获取的文本，而且 200 响应内的架构也丢失了。在我的根级别回复中，它是这样写的:

responses:
  '401':
    description: Unauthorized (ensure correct authorization header in the request)
  '403':
    description: Forbidden to perform the operation (ensure the client has correct role for the partition Id)
This responses field also missing from the document once I saved.

在我的根级别定义中，有 QueryResponse 架构:

  QueryResponse:
    properties:
      timestamp:
        example: '2019-08-09T10:04:50.49476Z'
        type: string
      message:
        example: 'Hello'
        type: string
    type: object

此架构保存后仍保留在文档中，但由于“路径”下的“响应”字段中缺少 $ref，因此也没有显示。

虽然我也尝试输入OpenAPI 3.0文档，但我按照官方文档重写了文档，我还在API管理中检查了对OpenAPI 3.0的支持，显然，预览功能下支持它。但是，当我将整个 3.0 文档输入编辑器并准备保存时，它显示一个错误:

一个或多个字段包含不正确的值:
解析错误:指定的 Swagger 版本未知。

我已经检查过，在 OpenAPI 3.0 中不再有“swagger”字段，而是被“openapi”字段取代，我将其放在文档的顶部:openapi: 3.0.0

请问2.0中缺少$ref或3.0中的错误是什么问题？如果有帮助的话，谢谢并非常感激。

<小时/>

更新

通过将以下字段放入响应中可以解决缺少的架构:

produces:
  - application/json

但是，现在它使其他响应(例如 400、401 和 403)具有显示空列行的“表示”列。我不希望这样，有没有其他方法可以仅将生成结果应用于响应 200？因为这是唯一具有 JSON 正文的响应。

此外，401 和 403 的 $ref 仍然缺失，描述取自根级别下的“响应”。

Answer 1

由于开发人员门户中没有显示空表示，操作详细信息页面的模板数据会导致空选项卡

我能够对模板进行这些更改，使其不会按预期显示它们，但仍然能够显示它们(如果存在)