Define schemas for models in the API?

slacker775
Conversationalist

Define schemas for models in the API?

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:
      tags:
      - Devices
      summary: List the devices in a network
      description: List the devices in a network
      operationId: getNetworkDevices
      parameters:
      - name: networkId
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkDevices'

...

components:
  schemas:
    NetworkDevice:
      type: object
      properties:
        lat:
          type: float
          nullable: true
        lng:
          type: float
          nullable: true
        address:
          type: string
          nullable: true
        serial:
          type: string
        mac:
          type: string
        wan1Ip:
          type: string
        wan2Ip:
          type: string
          nullable: true
        lanIp:
          type: string
        url:
          type: string
        networkId:
          type: string
        model:
          type: string
        firmware:
          type: string
        floorPlanId:
          type: string
          nullable: true
    NetworkDevices:
      type: array
      items:
        $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.

3 REPLIES 3
John-K
Meraki Employee
Meraki Employee

Would there be an advantage to re-defining the schema, rather than using the OpenAPI spec? We build the Python SDK from this spec. More info here:

 

https://developer.cisco.com/meraki/api-v1/#!get-organization-openapi-spec

slacker775
Conversationalist

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. 

The full output of the getOrganizationOpenapiSpec should consist of all paths, descriptions, operation IDs, parameters, and response schemas, so I imagine it has the information you need. Try running that call against your own organization ID for the full output.

Get notified when there are additional replies to this discussion.