Closed grosch closed 5 years ago
This should be addressed in 3.X.
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"
Sorry, that's with the 3.0.5 tag...forgot to specify that.
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?
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
I am having the same issue as above.
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!'
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'
And if oneOf
is 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"
@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.
@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 :smile:
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
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?https://github.com/swagger-api/swagger-ui/issues/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.
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.
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
@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'
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?
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???
@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.
@sontuphan Yes I can confirm that "Using example outside of schema and it is not showing example" for openapi: 3.0.0
Waiting for this to be fixed soon.
As this is proving problematic to resolve, please could you update the documentation to clarify the current limitations?
This is simple yaml file I've created that can not show example in swagger-ui.
Examples are not shown for openapi: 3.0.1
. Awaiting fix.
Looks like this bug is not easy to fix :( Is there any way to hide the field "Example Value" and only show the model ?
Any updates? This problem has been lasting for a long time😢.
We're working on adding support for example
. examples
support is going to take longer.
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.
Just to add some more colour to the issue, the online editor seems to show the examples just fine, not sure what makes it different than swagger-ui, it presumably uses the same component.
I am not seeing examples in the online editor. At least not in responses, when I reference a schema and then define the examples.
+1
+1
+1
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.
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.
This is so frustrating
Looks like I'll move back to Swagger v.2.0
Thanks for the update @webron. Is there anything the community can do to help move this along? Or is there any better place to track the progress?
@mchelen Any ideas, suggestions, mock-ups of what you'd expect the solution to look like, would be appreciated. We need to consider an end-to-end solution, especially given that the examples are also used in the try-it-out functionality and multiple example play a big part there, but also add to the complexity of the solution.
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"
}
Are there any updates with this? Or does anyone have a good workaround how to display multiple response objects that are possible with the same response code?
Is there a beta for this at least?
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.
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.
are there any updates on this?
Does this issue apply to using an example with a @RequestBody as well?
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
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?
This is still a problem in 3.0.2. Im using the workaround that @oleynikandrey proposed above until this is fixed.
Hopefully this will be fixed soon. The workaround given by @oleynikandrey works like a charm for response examples, but I can't find a way to make it work on requestBody examples.
Please fix it or gave us workaround for requestBody examples.
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: