swagger-ui: Examples are not showing

Everyone, some good news on this ticket (at last!). We’ve been working on a solution for multiple examples over the last couple of weeks, and are in the final stages of reviewing the changes, making sure they will work well with the try it out functionality and provide all the needed functionality.

There’s a tiny gotcha - we’re also working on a facelift for the existing UI, taking in a lot of the feedback we’ve received over the years and giving you a nicer looking, more functional product. The design of this solution is based on that facelift (more information on it will be available in the README in the upcoming weeks).

The good news is that we’re not going to wait for the facelift work to be done before implementing it, but rather to the best of our ability back port the functionality into the current design.

Once the design is done, we’re hoping to share the mocks here for you to see what’s coming (and you’re welcome to provide feedback as well). Also, once the design is finalized, it will be our top priority for implementation.

We understand how frustrating it’s been waiting for the implementation, and appreciate the patience, feedback and support from everyone. This is a matter of weeks now (and not referring to hundreds or dozens of those, much much less 😉).

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.

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

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 (#5432)
• example.externalValue isn’t supported (#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.

This is what I would suggest when several examples are set up :

Examples: [ Drop down with example label ] | Model

summary here if any (with enough spacing around)

{
    name: "payload example #1"
}

• You could use a drop down menu similar to content type selection (clearly visible).
• When clicking on ‘Model’ drop down is disabled and back on when clicking on “Examples”
• On change : replace summary and value, either in documentation or in try-it-out (in that case summary may not be displayed). If the user edits the payload in "try-in-out mode and switches from one example to another, he’ll loose his changes.

Can we get a big push on this issue to be fixed?

I am reading that this is a high priority item already, and the developers want to implement it “the right way”. But the issue has been open since 2017 Feb (over 2yrs now), and honestly pushing this for so long is NOT the right way.

Having multiple examples is very common/standard thing, and the openapi annotations already supports it (using the examples tag for multiple, and also having variating properties using anyOf, oneOf, and etc). So, the yaml structure part is already there, it seems that only the GUI is missing this.

Is there something else that’s preventing this from being implemented/delivered? Is it a UI design choice? There are no perfect solutions, but we can choose best solution at the time. Things will change and so will technology, so changing/improving it in the future is normal.

There is one way to show examples in swagger ui, but it’s not conform to openapi spec so you will get a warning:

openapi: 3.0.2
info:
  version: 0.0.1
  title: Show examples

paths:
  /method:
    post:
      summary: Foo
      responses:
        400:
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
          $ref: ''
          examples:
              Not JSON body:
                error:
                  code: json_parse_error
                  detail: Valid JSON object is expected
              Invalid parameter value:
                error:
                  code: invalid_parameter_value

Thanks @mchelen.

Please know that this is a high priority for us, but we want to get it right which is why it is taking longer. We cannot commit to a date but we’re doing what we can to promote the solution. It is not being ignored and is definitely not forgotten.

Unbelievable that this isn’t fixed. How hard is it to render examples for 400, 500, etc. the same way it already renders them for 200. This bug’s existence makes no sense, let alone why it’s existed for at least 3 years now.

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

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???

Hey folks, this is a known issue so you don’t need to keep replying with +1. Please use the “Subscribe” button or give the OP a thumbsup if you want.

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?

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: support@example.com
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"

@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'

Guys, this bug is exceptionally annoying as I need to give several examples for my collaborators on API usage. When do you plan to fix this?

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!'

January 2019, OpenAPI 3.0.n still an issue for parameter examples.

The problem with supplying singular “example”'s for properties is that it just automatically auto-fills the field even on optional fields.

What I’ve had to do is supply my example in the parameter description.

Another update! We’re very very close to finalizing the design for it, and hope it’ll be worth the wait. Unless we hit any major bumps we hope to share with you the design next week.

Reminder - the designs you are going to see are going to be based on a facelift we’re working on for Swagger UI. It will be a lot of change to take in. When commenting, please try to focus on the multiple example functionality, as hard as it may be. We understand you may want to comment on the facelift itself, and you’re welcome to share your thoughts (you won’t see everything in these mocks), but we may not be able to address all those comments within this ticket.

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

Do you plan on making that available on swagger-ui ? I followed several threads and a lot of people want that feature. It has been promised over more that 1 year now…I think it’s about time… Thanks

Examples are not shown for openapi: 3.0.1. Awaiting fix.

As this is proving problematic to resolve, please could you update the documentation to clarify the current limitations?

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

Would be nice if the specification / documentation didn’t include this if the functionality is incomplete. Would likely save a lot of people a lot of wasted time. Similarly, might be good to not have two completely separate instances of your documentation on your website at the same time.

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.

(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”.

The development of swagger-ui to do with oneOf and examples support seems to have stagnated.

I’m currently using ReDoc to render my OAS 3.0 spec and it supports both features very nicely.

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

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

there is my workaround: i wrote a description for the request so the description will display on top of the request for example:

post : {
    tags: {},
    summary: {},
    description: `
# Please copy then paste one of following example value bellow to request body value to test the \`api\` 
## Example value one
\`\`\`
{
   key: "value 1"
}
\`\`\`
## Example value two
\`\`\`
{
   key: "value 2"
}
\`\`\`
    `,
},

i hope this will help someone here until examples work

I noticed that examples do not show when building with webpack in production mode. However, it does work in development mode. The obviously downside is a 4mb bundle file.

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

@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!)

@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).

@mchelen that one is about oneOf and this one is about examples. But they may demand similar solution, in that sense they are related.

We’re working on adding support for example. examples support is going to take longer.

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

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”