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. 

[dong-dev]

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

[David-Yuen]

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.

[jemerald]

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.

[mchelen]

Is this issue related to #3803 ?

[jemerald]

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

[cobbce]

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.

[shockey]

@cobbce, I appreciate what you're saying, but the first screenshot of documentation is for the OpenAPI Specification (note the URL, /docs/specification/), not for Swagger UI.

The Specification and the UI as a tool are two distinct items managed by different groups of people (accordingly, the OpenAPI Technical Steering Committee and a team here at SmartBear), so changing one so accommodate the other isn't a good outcome for either group.

As for the second... that's not part of the Specification itself, but it is a general guide for writing OpenAPI documents that isn't related to Swagger UI. Note that we did take care to link to this issue there.

The problem here is valid, and it's because there's something in OpenAPI 3.0 that Swagger UI doesn't support (yet!).

[nicou50]

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

[dtolb]

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

@nicou50 there is an open PR #4092 that has multiple examples. I've started pulling it down instead of master and DIY until accepted.

I think the only reason it's still open is some style preferences.

[webron]

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 :wink:).

[webron]

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.

[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 reply@reply.github.com 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 (#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.

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