Accurate OData response schema

[joshbooker]

The response schema isn't exactly what's coming back from OData. For example, when you request Orders_Get the response body contains a context string followed by a values aray of Order objects like this:
{
"@odata.context": "https://microsoft-apiapp18a6d.azurewebsites.net/Northwind/v4/$metadata#Orders",
"value": [
{
"OrderID": 10248,
"CustomerID": "VINET",
"EmployeeID": 5,
"OrderDate": "1996-07-04",
"RequiredDate": "1996-08-01",
"ShippedDate": "1996-07-16",
"ShipVia": 3,
"Freight": 32.38,
"ShipName": "Vins et alcools Chevalier",
"ShipAddress": "59 rue de l'Abbaye",
"ShipCity": "Reims",
"ShipRegion": null,
"ShipPostalCode": "51100",
"ShipCountry": "France"
},
{...}
]}

With the following swagger we're not describing that the data will be inside the value array property:

    "responses": {
      "200": {
        "description": "EntitySet Orders",
        "schema": { "$ref": "#/definitions/NorthwindAPI.Models.Order" }
      },
      "default": {
        "description": "Unexpected error",
        "schema": { "$ref": "#/definitions/_Error" }
      }

As a result, some tools don't like it.

Perhaps this schema in swagger output would be better:

    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "title": "response",
          "type": "object",
          "properties": {
            "context": {
              "type": "string"
            },
            "value": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Order"
              }
            }
          }
        }
      },
    },

I'd like to do some more testing to see how this change might be beneficial, but reached a dead end so thought I'd share the idea if you're interested.

[rbeauchamp]

I was thinking about this too the other day, that the response model is not accurate. Its been good enough for human use but is probably not good for tooling use.

[rbeauchamp]

This is basically a bug: the response model should be accurate. I'll handle it.

[rbeauchamp]

@joshbooker Out of curiosity, what tools are you using against the swagger json?

[joshbooker]

Mostly Azure App Service Logic Apps. An OData project can be published as an API App then used as a custom connector in Logic Apps. The Logic Apps tooling reads swagger response schema and builds expressions against the json response. The current schema works great as the tooling displays a list of Order properties. The problem is, the tooling doesn't know the Orders array is wrapped in a value array. When manually edit expressions in code view of logic app designer I can successfully include .value - just the tooling doesn't do it for me. It tried to change the response schema in an Operation Filter as a test, but couldn't figure it out.

Additionally I've used swaggerhub.com and editor.swagger.io. They don't really act on response schema, so they're not really affected by this particular problem. They do show the response model so they were helpful in determining the suggested sample response schema in my post above.

Off topic: These tools have other issues. I cannot send a request because they include unused parameters in the URI. (/Orders?$expand=&$filter=&etc) OData doesn't like that. I tried including the swagger allowEmptyValue = false (which should be the default) but that had not affect. I'm of the opinion that they should leave off unused params like the swagger UI does. If anybody has any ideas here I'd like to know.

Anyway thanks for your hard work.

[joshbooker]

Oh yeah, also I noticed I'm not getting default error response schemas. I think the original OData swagger utilities was including these, but they got lost somewhere here. Pretty sure most tools will be happier having a default response to catch error message.

[ghost]

The response model is now correct for collections in v2.10.1. Please give it a try. An error response model will be an enhancement; please create a separate ticket for this. Thanks!

[joshbooker]

Thanks. Works Great! Error response issue here: #51