Create response object schema definitions

[mikewilson-dd]

Hey all. For the Meraki OpenAPI definition, rather than listing responses as objects and using the example field to demonstrate the format, please use OpenAPI schema objects and $ref (example). Any clients generated from this current definition will basically return raw maps. It would be better if these generated custom response objects.

[mvenditto]

+1
This will really ease the generation/maintainability of clients for statically-typed langs

[tottes200]

+1
Please do this!! Not having this makes generating the client a time consuming operation for statically-typed languages. Anytime there is an update or added endpoint I have to manually build that all out as it's not provided in the docs by default. We have 100k+ devices and rely heavily on the API. This would be one of the most beneficial updates.

[av1m]

+1
There are currently 955 "type": "object" in the current documentation.
I am currently fetching the sample answers and building my static models on them. Only that is not maintainable!

I had opened an issue (#156) but @TKIPisalegacycipher told me it wasn't for now.
@meraki, there is a large community that asks for features and who would like to contribute! Give us the opportunity to do it!
I seen that @dexterlabora is in the project and a many projects associated with Meraki, maybe he can help us on this subject

[dexterlabora]

Schema objects are on our ToDo list.
We are also looking into OpenAPI v3 and more..stay tuned.

[davidnmbond]

@dexterlabora - this is great news! Keep all these improvements coming - the Meraki API rocks👍🏼

[iamdexterpark]

This impacts development of my Golang API Library, so as a temporary solution I've forked the schema and will be adding objects and submitting PR's if that will help accelerate this effort.

[dexterlabora]

By popular request... response schemas are now being included in all future endpoints, with 1/3 of existing endpoints being updated in the latest release so far!

https://developer.cisco.com/meraki/whats-new/#!2022/7-2022

[av1m]

Here is an update :
Introducing OpenAPI v3 Support for the Meraki Dashboard API

[jamesmanning]

@dexterlabora Just trying to understand the post above that @av1m mentioned, should all calls have "complete" response schemas at this point in time? I see it in some but some of the calls I use like networks/{networkId}/clients/{clientId}/usageHistory still only say "array of object" with an example and no object schema yet. That one's example gives relatively small numbers for the "sent" and "received" values which doesn't make it clear to library authors that the values are 64-bit leading to bugs like json deserialization failing in some SDK's because the response includes values larger than 32-bit. The response to that call seems to be the same as networks/{networkId}/sm/devices/{deviceId}/cellularUsageHistory which documents the same properties (albeit as type=number,format=float, when it seems like they should be type=integer,format=int64, but that's much lower priority since float at least covers the larger range and should prevent deserialization failures)

Providing API response schemas are critical for strongly typed languages to ensure the data and types are as expected. OASv3 has enhanced these capabilities by providing flexible options to define dynamic, additive and conditional properties which the Dashboard API is taking advantage of. Creating SDKs for your favourite language should be easier and more reliable than ever before.

[av1m]

In fact @jamesmanning, some schemas are missing, such as the one you mention (getNetworkClientUsageHistory).

But in the idea, if the documentation is complete, you shouldn't have this kind of problem.
Indeed, the OpenAPI specification specifies types and the int64 type does exist, cf OAS: Data Types

For your example, we need this schema :

Actual

"responses": {
  "200": {
    "description": "Successful operation",
    "content": {
      "application/json": {
        "schema": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "example": [
          {
            "sent": 500,
            "received": 680,
            "ts": "2018-02-11T00:00:00.090210Z"
          }
        ]
      }
    }
  }
}

Expected

"responses": {
   "200":{
      "description":"Successful operation",
      "content":{
         "application/json":{
            "schema":{
               "type":"array",
               "items":{
                  "type":"object",
                  "properties":{
                     "type":"object",
                     "properties":{
                        "sent":{
                           "type":"integer",
                           "format":"int64",
                           "description":"The amount of data sent by the client in kilobytes."
                        },
                        "received":{
                           "type":"integer",
                           "format":"int64",
                           "description":"The amount of data received by the client in kilobytes."
                        },
                        "ts":{
                           "type":"string",
                           "format":"date-time",
                           "description":"The timestamp for the usage data."
                        }
                     }
                  }
               }
            },
            "example":[
               {
                  "sent":500,
                  "received":680,
                  "ts":"2018-02-11T00:00:00.090210Z"
               }
            ]
         }
      }
   }
}