OpenAPI v3 Officially Supported!

[DexterLaBora]

Introducing OpenAPI v3 Support for the Meraki Dashboard API

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:

1. API Design and Development: Design APIs in a standard, language-agnostic manner to reduce misunderstandings and rework.
2. API Documentation: Generate interactive, up-to-date API documentation that's easy for developers to understand and use.
3. Code Generation: Automatically generate client and server code in many languages, ensuring consistency between the API's implementation and its documentation.
4. API Testing and Validation: Create test cases and validate that the API's implementation matches its design.
5. API Management and Governance: Standardize APIs for easier management and governance within organizations.

New Use Cases Enabled by v3:

1. Content Negotiation: Define different schema and examples for different media types, supporting multiple formats like JSON and XML.
2. Linking and Callbacks: Describe complex, multi-step operations and outgoing 'callback' webhooks for asynchronous APIs and push notifications.
3. Security Enhancements: Support complex OAuth 2.0 flows and OpenID Connect Discovery with flexible security definitions.
4. Better Examples: Provide multiple examples for request bodies and responses to improve API documentation.

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:

1. Callback Support for Async Operations: The introduction of callbacks in v3 paves the way for better handling of complex, multi-step operations and outgoing 'callback' webhooks for asynchronous APIs and push notifications. This empowers developers to manage intricate, time-consuming tasks more efficiently, improving the overall performance. Stay tuned as we adopt some of these new features into the Dashboard API (hint: liveTools & actionBatches).
2. Enhanced API Definitions: 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. 
3. Improved Tooling and Validations: v3 introduces improved tools and validation mechanisms that streamline the API design, development, and testing processes. These enhancements ensure that the API's implementation aligns with its design, leading to a robust and reliable API experience.

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!

[daniel_abbatt]

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.

[DexterLaBora]

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. 

[daniel_abbatt]

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.