Specifying multiple examples for a given schema isn't possible

[elbee19]

We'd like to specify a few examples for our operations in our Swagger file, and I guess the only way to do so is to specify a body parameter and fill the 'example' property of the Schema object belonging to that operation.

The spec mentions that the 'example' field in the Schema object is of type object, so it can specify only one example.

[elbee19]

Also, if you change the spec to allow for multiple examples, it would be better if there was a way to specify the content type as well, I guess, for API's that can consume more than one content type.

[webron]

In that case, you can just have an object mapping a mime-type to its own sample. Tooling-wise, it's virtually impossible to 'parse' this value since it is free-form. I imagine that a tool like swagger-ui would just display it as-is.

[elbee19]

That sounds like it would work. The example property definition needs to be changed in the spec accordingly. Or, just set to 'Any' as you said on the Google groups thread.

[harishkashyap]

can we see an example of this implementation? @webron

[webron]

@harishkashyap - what do you mean?

[harishkashyap]

Looking for a definition or an example of how to have swagger display multiple examples for a given schema

[webron]

@harishkashyap - can you describe your case a bit more and where you'd actually like to include the sample? Would help me give you a more accurate response.

[harishkashyap]

@webron Thanks for your quick response. I am looking to see if its possible to show multiple examples for a given endpoint in swagger. As in the example at http://petstore.swagger.io/#!/pet/addPet , it is possible to specify different examples for different input parameter content types (json/xml) but is there a way to show different examples for a single input type?

[webron]

swagger-ui specifically will not show multiple examples, as that's not really defined by the spec. There's a similar specific solution in swagger-ui which is out of scope here, so if that's your intent, please open a ticket on that project.

[harishkashyap]

Thanks @webron . Can I get a link to that?

[robinemig]

I'm also interested in being able to provide multiple examples for an object, it would be nice if that was in the spec.

[juan-quiver]

+1

[max-k]

+1

[voycey]

+1 for this too - multiple examples per schema with the ability to add a description would be great to document specific states

[kigonya]

+1

[sbuljac]

+1

[shankie-codes]

I think there's a really nice use case here for doing a one-step-on-from stubs. If you can have multiple examples, then a GET for a single (i.e. a response defined by an object) could pick one at random, and a GET for all (e.g. a response defined by an array) could return all of the examples. I could imagine this being a pain to do, but it would be a nice feature.

[darrelmiller]

In the V3 spec you can to add multiple examples per schema.

[shankie-codes]

Ah cool, so then we just need to hassle the Swagger UI team to do something with it.

[darrelmiller]

@shankiesan Sure, just wait until after we get the implementer's draft out before giving them a hard time :-)

[shankie-codes]

That sounds like an awfully reasonable approach ;)

[piotrjozwiak]

+1
I need multiple samples too

[rprieto]

The V3 spec does have examples, but it looks like you can only provide an array of un-named request bodies or response payloads. It would be nice to extend it to

• be able to provide a user-friendly name for the request/response
• include request/response headers

Ideally I'd like to update https://www.npmjs.com/package/supersamples to generate OpenAPI-compatible entries that can be injected in an OpenAPI spec document. The benefit is generating these examples when running a unit-test suite: no need to keep examples up to date manually.

It could also be nice to group requests/responses together to show full end-to-end example, e.g. "here's a full example of an invalid payload". However that could simply be achieved (if required) by matching the user-friendly name of the request & response examples.

[webron]

@rprieto Would suggest filing a new ticket with these suggestion. Your comment here will just get lost.

[cweiske]

This is implemented in swagger UI already: swagger-api/swagger-ui#2651