Swagger/OpenAPI 3.0 问题与响应示例

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

您的定义是正确的，响应 example 出现在 Swagger Editor 3.6.5+ 和 Swagger UI 3.17.4+ 中。此外，Swagger UI 3.23.0+ 和 Editor 3.6.31+ 支持多个 examples。

Answer 2

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

Swagger/OpenAPI 3.0 问题与响应示例

Swagger/OpenAPI 3.0 issue with example on responses

swagger

swagger-ui

swagger-editor

openapi