[develop_2.0] Response Example Not Displaying

[Smolations]

This was working on master, but I have since switched to the develop_2.0 branch for features/fixes and it appears to be broken now. I verified that my JSON schema is valid, and that my produces/consumes (at the swagger object level) only include the 'application/json' mime type:

"paths": {
    "/media/{id}/experiment": {
        "get": {
            "description": "i am a description",
            "parameters": [{
                "type": "integer",
                "description": "Media's id",
                "name": "id",
                "required": true,
                "format": "int32",
                "in": "path"
            }, {
                "$ref": "#/parameters/page"
            }],
            "responses": {
                "200": {
                    "description": "standard response for successful HTTP requests",
                    "examples": {
                        "application/json": {
                            "id": 1,
                            "src": "blah/blah/blah.png"
                        }
                    }
                },
                "204": {
                    "description": "request processed, no content returned"
                }
            }
        }
    },

Only the response code and description show up in the UI, but no example. I thought that maybe the response rows were clickable/expandable (which would be a feature request for me because, say, 4 responses with examples showing the entire "Model | Model Schema" view would take up a lot of vertical space), but no dice.

[whitlockjc]

Since this is a regression, I've added it to the M2 milestone.

[Smolations]

Oops! I meant to post this issue in the swagger-ui project. Does that project pull in this library? If not, I can re-post this issue in the correct project. 🙈

[whitlockjc]

swagger-ui uses swagger-js to generate some of its UI. Weird, I know, but for the next release of swagger-js and swagger-ui, this will be the case. We'll be cleaning this up in a future release.

[whitlockjc]

This should be fixed if I understand it. Basically, swagger-ui uses swagger-js's Model#createJSONSample to render the JSON representation when available. Pull request #303 makes it so that if there is an application/json example that is either a JavaScript object or a JSON string, we will use that instead of having the Model create its own JSON sample.

[Smolations]

Wow, ultra-quick turnaround! Thanks @whitlockjc, awesome job!

[Smolations]

@whitlockjc OK, so, I just got around to retrying this functionality, and I am still seeing no examples get spit out. I literally just built swagger-js and swagger-ui for an edge release (as described here). My JSON still looks similar to the above, but there is nothing rendered where the Model/Model Schema normally would be. Did it regress again? Are there tests written around this feature?

EDIT: Just checked the merged PR and it looks like there are indeed tests around this. So now I'm just vexed that it isn't rendering, lol.

[Smolations]

I also checked with a JSON string, e.g.

"examples": {
  "application/json": "{ id: 1, src: 'blah/blah/blah.png' }"
}

...to no avail. =[

[whitlockjc]

I've no idea. I know that swagger-ui has been under constant development so it wouldn't surprise me if there was some regression. Let me go look around and see if swagger-ui is indeed still using this.

[whitlockjc]

It seems that your response definition is wrong. You provide an example but do not provide an actual schema to describe your response. A schema-less response is considered to be a void response, which means no response.

[whitlockjc]

As for how swagger-ui is using swagger-js to render the operation view, check this out:

https://github.com/swagger-api/swagger-ui/blob/9d8ccc40dc5b051b61c80f316e5cf47bf344ddc6/src/main/javascript/view/OperationView.js

[Smolations]

@whitlockjc Ahhhhh ok! Yup, once I added a schema the example showed up as expected! I suppose the only action item that could come from this excursion is to add some documentation to the swagger-spec showing how to add an example and clearly stating that a schema is required if examples are to be used. =]

Thanks for the clarification!

[whitlockjc]

Well, what good is an example for a void response? So it's less that you need a schema for the response example to be displayed and more that you've provided a superfluous example for a void response when you don't have a schema. Make sense?

[webron]

@Smolations - The specification will not specify it because it's not a constraint. Choosing to display or not is a tooling decision. Logically, it doesn't make sense to display an example for something that doesn't exist.

[Smolations]

My original interpretation was that i could provide schema || example, but that is clearly not the case. When you say "void response," do you mean a response which does not return a JSON payload? Perhaps you could expound on that.

Anyway, time has been taken in the spec to point out which properties on objects are required, either always or conditionally based on values of other properties. Given the spec for a Response Object, only a description is required which implies that any combination of the other properties could be provided and the UI should render correctly.

I totally get what you are saying, and I pretty much agree with you, but if I experienced confusion when I felt like I was following the spec, then surely someone else will too. Or perhaps I'm an anomaly. 👼 lol

[webron]

A void response is a response that returns nothing, be it a JSON payload, a number, yaml, html, xml or anything else. This would normally be alongside a 204 HTTP status code, for example. Please take a moment to read the description of the schema property of a response - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responseSchema. While it doesn't say void specifically, I believe it's clear about the meaning of it when it is not there.

[Smolations]

@webron Thanks for the clarification. And to answer the question posed by @whitlockjc, I agree that it doesn't make sense for an example to accompany a void response. I suppose it amounts to common [technological] sense, I just was paying more attention to the Required text in descriptions, as well as any info in those descriptions around conditional requirements.

As we've been having this conversation, I believe I have uncovered a bug around this feature (or perhaps with the newly-implemented "allOf" support in schemas): #459