Swagger/OpenAPI 3.0问题以及响应示例 [英] Swagger/OpenAPI 3.0 issue with example on responses

问题描述

这是我正在Swagger编辑器上在线查看的OpenAPI 3.0定义的简化版本.我正在尝试针对错误代码401和403的两个响应，它们共享相同的架构，并显示不同的示例-这似乎不起作用，并且我仍然将引用的类型作为示例.

This is a simplified version of my OpenAPI 3.0 definition I'm viewing on the Swagger Editor online. I am trying to have the two responses for error codes 401 and 403, that share the same schema, show different examples - this doesn't seem to work and I still see the referenced type as example.

您能帮我弄清楚定义有什么问题吗?

Can you help me figuring out what's wrong with the definitions?

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

推荐答案

您的定义正确，并且响应example显示在Swagger编辑器3.6.5+和Swagger UI 3.17.4+中.此外，Swagger UI 3.23.0+和Editor 3.6.31+支持多个examples.

Your definition is correct, and the response example show up in Swagger Editor 3.6.5+ and Swagger UI 3.17.4+. Also, multiple examples are supported in Swagger UI 3.23.0+ and Editor 3.6.31+.

这篇关于Swagger/OpenAPI 3.0问题以及响应示例的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！