The real difference is that the way the responses are currently defined in the docs, there is nothing for a generator tool to use to build out response classes. It just knows that there will be a JSON object with stuff inside. If the response is defined, there can be type validation and all of the various getters/setters. The actual API is completely unchanged, there is just better definition regarding the data actually returned.
... View more
Would it be possible to actually define the schema for the responses in the API? I'm using a generator tool (janephp) to generate a library to work with the Meraki API and if the models are defined in the schema (vs using x-is-dynamic) really helps to get entity classes defined with various error checking defined in the API spec - property types, nullable or not etc. As an example, here's a workup for the getNetworkDevices API call: get:
summary: List the devices in a network
description: List the devices in a network
- name: networkId
description: Successful operation
$ref: '#/components/schemas/NetworkDevice' With just having x-is-dynamic, I just get an object with a batch of public properties and my client itself has no knowledge of anything so I'd have to do a whole lot of checking if a property exists etc which makes for some ugly code. Even the recent moves to finally stating the responses are application/json instead of text/plain has helped a lot. It's really starting to get to where we can put together some nice automations to make managing our environment a lot easier.
... View more