CODEWITHSUNDEEP
swaggerswagger-uiswagger-editoropenapi
Iacopo Pace
Iacopo Pace

Reputation: 187

Swagger/OpenAPI 3.0 issue with example on responses

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

Upvotes: 7

Views: 7425

Answers (2)

Jitter
Jitter

Reputation: 1

I am not sure whether this is at the heart of your problem but I noticed that the HTTP status codes in your path respone sections aren't given enclosed in quotation marks. The OpenAPI specification v3.x (in contrast to v2.x) makes this mandatory which you might want to look up here:

Upvotes: 0

Helen
Helen

Reputation: 97540

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+.

Upvotes: 2

Related Questions