We are doing network automation work for our clients and the cnMaestro REST API has been a huge help. Recently I dug into the deployment and found that there is an included OpenAPI spec. I tried to use it to generate clients that would ease our job to communicate with cnMaestro but I stumbled upon several errors in the definition. I understand that since it’s not provided in the downloads, it probably isn’t supported but you may want to fix them anyway.
- In OpenAPI v3 there is no ‘null’ type as used in
build/device/configuration/enterprise_wifi/wlan_definitions.yamlat line 113 and many other places. See here. Instead there is the
nullablefield. In this example the
time_rangeshould be defined as follows:
time_range: description: 'Time range in the format "HH:MM-HH:MM"' type: string pattern: >- ^((?:\d:[0-5][0-9]|2[0-3]:[0-5][0-9])(?:\s?)-(?:\s?)(?:\d:[0-5][0-9]|2[0-3]:[0-5][0-9]))$ nullable: true
schemaobject cannot contain an array as in
schemas/guest_portal.yamlat line 66. It should be:
schema: $ref: '../build/guest_portal.yaml#/Api.V1.PUT.Services.wifi-enterprise.Guest_Access.Portals/body'
schemas/guest_portal.yamlline 50, the definition of the array is missing. As per the
schemadefinition, if the type is
itemsobject must be present. For example:
properties: whitelist: type: array items: type: string
- In the OAuth security scheme definition, the
scopesfield is missing but it is required on the spec.
- Typos: the word
descriptionis mistyped as
descriptinin some files. The word
defaultis mistyped as
- You cannot augment the definition of a referenced object as in
build/device/configuration/enterprise_wifi/ap_group.yamlline 35. Items of
schemadefinition but this
requiredis not. Similar case in
producersfield defined in several files does not exist in the spec. It probably is a leftover from Swagger v2
- There are no schemas defined for any data returned by cnMaestro. Thus the data returned cannot be parsed by generated clients.
It would be really nice and helpful if you released the OpenAPI spec since you’ve done most of the work to develop it anyway.