Response and Schema Examples

[pdurkim]

In the right-most column, the auth0 API docs show samples of the response and schema. How do you define these samples? So, if I have a swagger definition:

swagger_api :index do
  summary 'List Discussions'
  param :path, :workroom_id, :integer, :required, "ID of workroom to filter discussions"
end

how and where can you define example responses and schemas?

[voycey]

This would be useful, they are included in the standard swagger-ui - any hints on where to enabled these in this awesome theme?

[davidkeaveny]

If example responses and schemas are defined in your Swagger definition file, then it should just work out of the box for you. (Nice touch: if you shrink the width of your screen to tablet-or-lower resolutions, the responsive design that @jensoleg has put together hides the sample/schema column, and adds a Show Sample button to display them in a pop-up instead).

In the Swagger definition for an API endpoint, it would look something like this:

"responses": {
    "200" : {
        "description": "The operation completed successfully",
        "schema": {
           "$ref": "#/Namespace.To.Your.Model"
        },
        "examples": {
            "application/json": {
                id: 12345,
                name: "Sample value",
                created: "2016-02-14T06:02:03"
            }
        }
    }
}

I'm using Swashbuckle to generate the Swagger definition from my ASP.NET WebAPI.

[voycey]

It works for the responses but I dont have any that describe the exceptions, the examples are defined in my definition block - not sure if that makes a difference?

[davidkeaveny]

As in a model/schema and sample when the response is e.g. a 400 Bad Request?

[voycey]

Yep - e.g:

"NoCampaignFoundError [data]": {
            "type": "object",
            "properties": {
                "code": {
                    "description": "HTTP Error Code",
                    "type": "integer",
                    "format": "int32"
                },
                "message": {
                    "description": "Description of Error",
                    "type": "string"
                },
                "exception": {
                    "description": "Exception Details",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/ExceptionObject"
                    }
                }
            },
            "example": {
                "success": false,
                "data": {
                    "message": "No campaign found",
                    "url": "/impressions/beacon.json",
                    "code": 404,
                    "exception": {
                        "class": "Cake\\Network\\Exception\\NotFoundException",
                        "code": 404,
                        "message": "No campaign found"
                    }
                }
            }
        },

[davidkeaveny]

And that renders successfully in this fork? I can't even get Swashbuckle to generate that part of the definition, so I can't try it out in my API.

[voycey]

No sorry that was my point, the error examples dont render in this but they work fine in the vanilla swagger-ui, I assume that those template sections have been removed but not sure where to look?

[wazodevs]

Nowadays, we're having the same issue. It's only happens with array/list models. If we use a simple model (object, string...) it works.

Wrong Rendered:

`HTTP Status Code	Reason	Response Model	Headers
400	BadRequest	Array[object]	`

Expected Rendered:

`HTTP Status Code	Reason	Response Model	Headers
400	BadRequest	[{"codigo": 0,"mensaje": "string"}]	`

This wrong rendered only happens with all request that aren't 200 (404,500...) and the reponse model is an array/list.

¿Any idea what's happening?