Question

这是我正在Swagger编辑器在线查看的OpenAPI 3.0定义的简化版本。我试图让错误代码401和403的两个响应共享相同的模式，显示不同的示例 - 这似乎不起作用，我仍然看到引用的类型作为示例。

你能帮我弄清楚这些定义有什么问题吗？

openapi: 3.0.0
info:
  version: '1.0'
  title: A service
paths:
  /doSomething:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: A string
      responses:
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Denied'
components:
  responses:
    Unauthorized:
      description: The endpoint cannot be reached because the request is not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
    Denied:
      description: The request's authorizations don't match the required ones needed to access the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: permissions denied
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string

Answer 1

您的定义是正确的，响应示例显示在Swagger Editor 3.6.5+和Swagger UI 3.17.4+中。（在这些版本中添加了对content.<media-type>.example的支持。）

请注意，还不支持复数examples和模式。您可以按this issue进行更新。

Answer 2

我不确定这是否是您问题的核心，但我注意到您的路径响应部分中的 HTTP 状态代码没有用引号括起来。 OpenAPI 规范 v3.x（与 v2.x 相比）强制执行此操作，您可能需要在此处查找：

Swagger / OpenAPI 3.0问题以及响应示例

2 个答案: