Examples are not showing

[grosch]

Using v2.2.10 of Swagger UI I'm not seeing examples at all. When I'm editing with swagger-editor I do see the example shown properly. I used this for my method definition:

  /person/{email}/create:
    post:
      summary: Create a new account
      tags:
        - Person
      parameters:
        _... chop ..._
      responses:
        201:
          description: The new SQL ident and sport details 
          examples:
            application/json: |
              [
                12,
                [
                  {
                    "sql_idnet" : 12,
                    "name" : "Basketball"
                  },
                  {
                    "sql_ident" : 13,
                    "name" : "Ice Hockey"
                  }
                ]
              ]
        412:
          description: The email address is already in use. 

[webron]

This should be addressed in 3.X.

[grosch]

It kinda shows the example now, but not in a good format. It appears like so:

"[\n 12,\n [\n {\n "uid" : 12,\n "name" : "Basketball"\n },\n {\n "uid" : 13,\n "name" : "Ice Hockey"\n }\n ]\n]\n"

[grosch]

Sorry, that's with the 3.0.5 tag...forgot to specify that.

[giuliopulina]

I'm also experiencing bad formatting on examples on version 3.2.2. Do you know if it's something that easy to fix? Does it depend on some configuration?

[sithmein]

It seems that for OpenAPI 3.0.0 files examples are not shown at all:

openapi: 3.0.0
info:
  title: OpenAPI Test
  description: Foo
  version: 'Wed Oct 18 14:26:19 CEST 2017'
  contact:
    name: thor
paths:
  /:
    post:
      summary: Executes a job from the workflow
      operationId: executeJob
      requestBody:
        description: Simple input parameters for the job
        content:
          application/json:
            examples:
              default:
                summary: Default values from the workflow
                value: |
                  {
                    "string-input-1": "string value",
                    "int-input-7": 42,
                    "json-input-2": {
                      "a": "b",
                      "x": 42
                    }
                  }
      responses:
        '200':
          description: Status and result of the job

[rickmzp]

I am having the same issue as above.

[jgoodknight]

I am having the same issue. According to the docs, this is the correct syntax for examples, but it does not appear in the ui. example(s) singular does, though. I've made a code snippet which demonstrates this.

openapi: 3.0.0
info:
  version: V0
  title: Example
  description: Showing how examples does not show up

servers:
  - url: localhost
    description: Production Server

paths:
  /examples:
    post:
      summary: Multiple examples do not appear in ui
      description: 'Request info from the server '
      requestBody:
        description: The payload of search terms 
        required: true
        content:
          'application/json':
            schema:
              type: object
              description: All the parameters you can send to the search engine
              properties:
                search:
                  type: string
                  description: The phrase being searched for 
                location:
                  type: string
                  description: any string which describes the desired location of the job; will be parsed by the server
            examples:
             typical_user:
               summary: 'Basic Query'
               value:
                 search: 'pizza'
                 location: 'Chicago'
             second:
               summary: 'More Involved Query'
               value:
                 search: 'summer camp'
                 location: 'Dallas, TX'
             other:
               summary: 'other shtuff'
               value:
                 search: 'janitor'
                 location: 'Omaha, NE'
      responses:
        '200':    # status code
          description: 'A JSON array of suggested jobs and related info on the query'
          content:
            'application/json':
              schema:
                type: object
                description: All the parameters returned from the search engine
                properties:
                  result_string:
                    type: string
                    description: The search result
              examples:
                typical_user:
                  summary: "first result"
                  value:
                    result_string: 'deep dish'
                second:
                  summary: "second result"
                  value:
                    result_string: 'camp wisdom'
                other:
                  summary: "third result"
                  value:
                    result_string: 'ProCleaners Inc.'
  /example:
    post:
      summary: One example does show
      description: Request info from the server 
      requestBody:
        description: The payload of search terms 
        required: true
        content:
          'application/json':
            schema:
              type: object
              description: All the parameters you can send to the search engine
              properties:
                search:
                  type: string
                  description: The phrase being searched for 
                location:
                  type: string
                  description: any string which describes the desired location of the job; will be parsed by the server
              example:
                search: 'things to do'
                location: 'Omaha, NE'

      responses:
        '200':    # status code
          description: 'A JSON array of suggested jobs and related info on the query'
          content:
            'application/json':
              schema:
                type: object
                description: All the parameters returned from the search engine
                properties:
                  result_string:
                    type: string
                    description: The phrase being searched for 
                example:
                  result_string: 'lots of things!'

[marcocamacho]

Just to raise more awareness on this issue, I am using an external example as defined in the openApi 3 documentation and UI is not rendering. I used Swagger UI last updated on early November 2017 859edbf

openapi: 3.0.0
info:
  version: 1.0.0
servers:
- {url: 'http://place-holder-server.com/rest'}
tags:
- {name: PhoneSystemKitPBX, description: ...}
paths:
  /pbxsettings:
    get:
      parameters: []
      responses:
        '200':
          description: "- Get phone system kit pbx successfully \n\n\t\t Message:\"
      tags: [PhoneSystemKitPBX]
    put:
      parameters: []
      responses:
        '200':
          description: "- Put phone system kit pbx successfully \n\n\t\t Message:\"
      tags: [PhoneSystemKitPBX]
      requestBody: 
        description: user to add to the system
        content: 
          application/json:
            schema:
              type: object
              properties:
                foo:
                  type: string
            examples:
              jsonObject:
                summary: User Example
                externalValue: 'http://domain.com/phoneSystemKitPBX.json'

[Frederick888]

And if oneOfis used, even the auto-generated examples are not showing.

openapi: 3.0.0
servers:
  - url: 'https://www.example.com'
info:
  description: |
    Test
  version: "1.0.0-oas3"
  title: Test Documentation
  termsOfService: 'https://www.example.com/terms'
  contact:
    email: [email protected]
tags:
  - name: test
    description: Example
    externalDocs:
      description: Homepage
      url: 'https://www.example.com'
paths:
  /history:
    post:
      tags:
        - test
      summary: Queries historical results
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/QueryRequestTimeRange'
                - $ref: '#/components/schemas/QueryRequestId'
            examples:
              QueryRequestTimeRange:
                $ref: '#/components/examples/QueryRequestTimeRange'
              QueryRequestId:
                $ref: '#/components/examples/QueryRequestId'
        description: Query statement, could either be a time range or a single id
        required: true
components:
  schemas:
    QueryRequestTimeRange:
      type: object
      properties:
        from:
          type: string
          format: date-time
          description: Time range beginning (inclusive)
        to:
          type: string
          format: date-time
          description: Time range ending (inclusive)
    QueryRequestId:
      type: object
      properties:
        id:
          type: string
          description: Accession ID
          example: 76f48d01c0ae0f3dc6fd84f42e01e6ad
  examples:
    QueryRequestTimeRange:
      value:
        from: "2017-12-03T00:00:00Z"
        to: "2017-12-06T23:59:59Z"
    QueryRequestId:
      value:
        id: "76f48d01c0ae0f3dc6fd84f42e01e6ad"

[webron]

@Frederick888 that's because we need to figure out how to handle it. Generating examples when oneOf or anyOf are being used is not simple.

[Frederick888]

@webron Yea, I know, and that's why I'm not filing a new issue. I think getting my examples rendered would be good for now 😄

[ffissore]

As a heads up, 3.9.0 does not show multiple examples yet. As a use case, multiple examples are why I've upgraded to openapi 3

[fat-panda]

OpenApi3 in theory supports examples - https://swagger.io/docs/specification/adding-examples/
But the swagger editor (Swagger-UI), OAS 3.0 example/examples is not yet implemented?#2651

Having said that, the Spec is still rendered with many schema errors...
Trying to re-use examples by defining them in components and getting Schema errors: Schema error at components.examples['UserId'].

Components
examples:
UserId:
fault:
code: "badRequest"
httpStatus: 400
detail: "User Id Format is not valid"
message: "You supplied invalid request details"
serverDateTime: "2018-01-17T10:38:54.623+1300"

Redefining exactly as how the Documentation states it (https://swagger.io/docs/specification/adding-examples/) still causes errors.

[3mp3ri0r]

Any update on showing example for content with object reference ($ref) schema type? I'm really confused how to show example with their own documentation here.

[herb123456]

Can not show example either.

openapi: 3.0.1
info:
  title: test
  description: test
  version: 0.0.1
servers:
  - url: 'http://localhost:8080'
paths:    
  /test:
    post:
      summary: 'test'
      description: 'test'
      requestBody:
        description: ""
        content: 
          'application/json':
            schema:
              $ref: '#/components/schemas/test'
            example:
              id: "test"
      responses:
        400:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/testRes'
              example:
                result: 'aaa'
                message: 'bbb'
components:
  schemas:
    test:
      type: object
      properties:
        id:
          type: string
          description: 'id'
    testRes:
      type: object
      properties:
        result:
          type: string
        message:
          type: string

[EmanuelSanchez]

@3mp3ri0r, you can work around it with the following, although it have a problem, it will show the same example every time you use $ref.

components:
  schemas:
    User:
      properties:
        id:
          type: integer
        name:
          type: string
     example:
        id: 5
        name: 'Petra'

[normenmueller]

I'd like to add that parameter examples are also not displayed.

parameters:
  - in: query
    name: fields
    description: One or more fieldss
    required: true
    schema:
      type: array
      items:
        type: string
    style: form
    explode: false
    examples:
      oneField:
        summary: Example of a single field
        value: [foo]   # ?fields=foo
      multipleFields:
        summary: Example of multiple fields
        value: [foo, bar, baz]   # ?ids=foo,bar,baz

These examples are displayed nowhere at Swagger UI. Or am I missing something here?

[sontuphan]

Using example outside of schema and it is not showing example. Btw, this issue opened in Feb 2017, now is Jun 2018 and it is still opening. WTH swagger team doing???

[webron]

@sontuphan we mostly lurk on issues and see how they annoy users.

Alternatively, we constantly work on improvements and additions.

The good news is that example rendering is prioritized fairly high, though we cannot provide an ETA.

[muratsplat]

@sontuphan Yes I can confirm that "Using example outside of schema and it is not showing example" for openapi: 3.0.0

[Shwetap05]

Waiting for this to be fixed soon.

[webron]

And here it is, the upcoming design. The file is rather large, so don't forget to click on it to see the full version.

You'll notice many changes that are part of the overall facelift we're working on as well. For now, we'll back port the multiple examples support into the current design. You're pretty much getting a sneak peek into what's coming. For feedback, please try to focus on the actual multiple example implementation, but we'll read through everything.

[keith-bennett-gbg]

That looks pretty cool! Would the drop-down menu respond to scroll wheel events and/or up/down arrow key events? I navigate websites a bunch using keyboard and it would be handy to be able to tabstop into the drop-down menu's focus and use arrow keys or scroll wheel to quickly compare examples.

[leggsimon]

@webron This looks great!

Just slightly to add to @keith-bennett-gbg’s comment, would be good to ensure that keyboard and screen-reader accessibility is also factored in with these designs (things like ensuring the full text of the selection boxes are read out rather than being stopped at an elipsis).

[BostonKevin]

This does look good, but would anyone know if examples for enum parameters are supported with this planned feature? Suppose you need to document a parameter that can represent 2 distinct values, say a user-key and a group-key. This choice can be modeled in YAML with Swagger Editor easily, as shown here:

        - name: special_key
          in: path
          description: The key of the group or user.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            enum:
              - user_key
              - group_key

For the parameter special_key, the UI will present a drop-down menu that lets you select user_key or group_key. The Swagger Editor only lets you specify a single example. So would it be possible - with the new design - to specify an example for each enum value of a parameter?

[adriancislo]

What version of docker image I should use to expect multi examples work? I use :latest and it does not seem to work

[BostonKevin]

They don't work with any version. That's the problem On Tuesday, June 18, 2019 adriancislo <[email protected]> wrote: What version of docker image I should use to expect multi examples work? I use :latest and it does not seem to work — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[Ciprian-Donisa]

Is there any estimated date when this is going to be solved? Thanks!

[shockey]

Okay! Time to close this one out 😄

We just released Swagger UI 3.23.0, which includes support for examples in Parameters, Request Bodies, and Responses 🎉

There are some limitations right off the bat:

• Examples in Header Objects aren't supported (Header.examples is ignored #5432)
• example.externalValue isn't supported (Example.externalValue is not displayed #5433)

Beyond that, there are always going to be combinations of things within OpenAPI that won't work perfectly with our first swing at a new feature -- you can help us improve by sending over high-quality bug reports that help us understand your use case.

All things considered, we think we've nailed down a good set of base functionalities for examples, along with a sensible user interface for viewing and interacting with them.

Thanks to everyone that has contributed to this issue! It was all very helpful to have on hand while we worked on this.

If you have any bug reports or improvement suggestions for the new implementation, please open a new issue and follow our issue template. This thread is much too long to be used for tracking issues going forward, so any new reports here won't be addressed.

[kholmukhamedovme]

@shockey when it will be available to use in SwaggerHub?

[shockey]

@kholmukhamedovme can't say for sure -- they operate on their own release schedule that we don't have visibility into.

(Generally though, new things in the OSS appear in SwaggerHub within a month. No promises, just an observation!)

[inet-cologne]

(Generally though, new things in the OSS appear in SwaggerHub within a month. No promises, just an observation!)
Ok, in 2 month, one year is over and the examples issues in swaggerHub UI still are not fixed.

If I define my samples in components/examples and $ref from responses

1. bug: the examples do not show in the UI-docs section on the right but the samples shows the $ref-line (see screenshot) and
2. nice2have: it would be nice to have a "Examples" section in the Nav on the left like "Schemas".

[hkosova]

@inet-cologne most likely you're using $ref with example (singular) instead of examples (plural). The correct syntax for referencing examples is:

responses:
  '200':
    description: ok
    content:
      application/json:
        schema:
          ...
        examples:
          eventSuccessfulExample:
            $ref: '#/components/examples/eventSuccessfulExample'

If this suggestion does not solve your problem, please open a new issue and provide the requested details.

[inet-cologne]

@inet-cologne most likely you're using $ref with example (singular) instead of examples (plural). The correct syntax for referencing examples is:

responses:
  '200':
    description: ok
    content:
      application/json:
        schema:
          ...
        examples:
          eventSuccessfulExample:
            $ref: '#/components/examples/eventSuccessfulExample'

If this suggestion does not solve your problem, please open a new issue and provide the requested details.

Thanks! That did it.

[erescobar]

I have a problem related to examples. I'm including examples and, is swaggerhub they are shown but when I generate the code for spring boot, the code does not contain the examples.

[Sachin-Suresh]

I can see the parameter examples in the Swagger Editor. But when I download the HTML 2 client, even though the HTML has json code for example, it doesn't appear in the output. Can anyone help me on this?

Below is my Swagger editor code which is perfect:

paths:
  /user/register:
    post:
      tags:
        - Drupal API Library > Auth
      summary: Create new user
      description: >-
        #### This REST API is used to register a new authenticated user.


        **NOTE:** When you are registering a new user, ensure you are logged out
        of the current user.


        This API uses `Basic Auth`. The headers you need to use in this API are
        shown below:
      requestBody:
        #description: test description here
        #required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - mail
              - pass
              example:
                _links:
                  type:
                    href: https://test.com/rest/type/user/user
                name:
                  - value: test1g
                mail:
                  - value: g**********@hotmail.com
                pass:
                  - value: T******g
              properties:
                name:
                  type: string
                  description: Name of the user
                mail:
                  type: string
                  description: User's email address
                pass:
                  type: string
                  description: User's password

The below is the HTML 2 generated code which doesn't show the example output:

...
...
<script>
<script>
											$(document).ready(function() {
												var schemaWrapper = {
													"content": {
														"application/json": {
															"schema": {
																"x-content-type": "application/json",
																"required": ["name", "mail", "pass"],
																"properties": {
																	"name": {
																		"type": "string",
																		"description": "Name of the user"
																	},
																	"mail": {
																		"type": "string",
																		"description": "User's email address"
																	},
																	"pass": {
																		"type": "string",
																		"description": "User's password"
																	}
																},
																"example": {
																	"_links": {
																		"type": {
																			"href": "https://sangriadrupal.wellcure.com/rest/type/user/user"
																		}
																	},
																	"name": [{
																		"value": "test1g"
																	}],
																	"mail": [{
																		"value": "g**********@hotmail.com"
																	}],
																	"pass": [{
																		"value": "T******g"
																	}]
																}
															}
														}
													}
												}

What is wrong in the HTML code?