We are excited to announce the rollout of OpenAPI v3 support for the Meraki Dashboard API!
Our API has transformed significantly starting with the adoption of Swagger, now known as OpenAPI v2. The integration of the OpenAPI Specification has been crucial in streamlining our API development process and crafting a seamless experience for developers. Today, we're taking a significant leap forward by adopting the OpenAPI v3 Specification. This significant update is a testimony to our commitment to fostering a high-quality API contract and equipping our developer community with the most up-to-date tools and technologies.
Great!, ...What's it used for?
Use Cases:
New Use Cases Enabled by v3:
Key Improvements
The transition to OpenAPI v3 brings a lot of great stuff and new possibilities for developers. Here are some of the initial improvements we're implementing out of the gate:
Get Started with OpenAPI v3
Starting with OpenAPI v3 support for the Meraki Dashboard API is straightforward. Visit our Meraki OpenAPI GitHub repository at https://github.com/meraki/openapi where you can find OpenAPI specifications for the Meraki Dashboard API. Here are shortcuts to the v1 & v1-beta specifications in JSON format if you want to have a quick peak under the hood.
Alternatively, you can explore the Developer Hub at Meraki.io for comprehensive documentation, sample code, and integration guides to start taking advantage of the Meraki Dashboard API.
Please share your OpenAPI v3 creations and stories with us!
Thanks for this great work, looking forward to investigating in depth.
Out of interest are the examples and models tightly linked and are they generated from code. I ask because in the past some examples have referred to fields not existing in the documentation and then the actual responses have included fields not present in either.
So I guess I'm asking is the OpenApi definition code generated as part of the actual API methods and so will always be accurate to the underlying code generating the responses or is it hand crafted to an extent?
I know there are so many different ways of generating OpenApi specs, e.g. from models and actions and comments.
Thanks in advance.
Thanks for the feedback and good question!
The API specification is generated based on our internal code. That being said, when we first launched support for Swagger/v2 we only included "examples" for the API responses. These did come from code, but as human typed comments. Obviously we had to improve that to ensure we could completely and accurately document all of the properties.
Over the past year, we have been diligently backfilling "response schemas" that should accurately define all parameters and their respective types. Examples are then validated against the schema as part of our build process. All new API endpoints will be fully documented and we have just a few more existing endpoints to polish up. By supporting OpenAPI v3, we are able to now define the remaining "odd balls" in our API by using new oneOf, allOf and manyOf schema types among other flexible solutions.
Thanks, that sounds excellent; we use the spec internally to validate all our strongly typed interfaces to make sure we've got the request/response models correct etc and of course this only fully works for those that have been specified so anything in this area is welcomed.
I can't remember what the spec allows but another thing we struggle with is whether a property on a response object will always be there or whether sometimes it isn't, and/or when it is can have a null value. We currently have to guess which response properties might be null and define our models appropriately, this useful for the consumer of the library as they'll know when to expect values or not.