The OpenAPI Specification Version 3.0 Highlights
25 Jan 2017
I am impressed with the work that the Open API Initiative (OAI) working group has accomplished with the version 3.0 release of the OpenAPI Specification. I have had zero involvement in moving the specification forward (something I'm changing), and after coming back to the effort I am impressed with what they've prioritized, and accomplished for this release.
The highlights in version 3.0 of the OpenAPI Spec for me are:
- Components - The new components architecture really reflects "APIs" in my opinion, making things modular and reusable.
- Body - Catching up when it comes to allowing the body to be defined separately from the headers and parameters.
- Content Negotiation - You can now define content objects to define the relationship between response objects, media types, and schema.
- Linking - It isn't hypermedia, but it is definitely a nod towards hypermedia, allowing the linking of objects.
- Webhooks - You can now define callbacks that can be attached to a subscription operation describing an outbound operation.
- Schema - Increased investment in JSON Schema, including support of `oneOf`, `anyOf` and `not` support, as well allowing for alternative schema now.
- Hosts - You can now have multiple hosts, allowing you to more narrowly define the host for each path.
- Examples - Allows you to better describe, and provide examples of APIs responses and requests.
- Version Identifier - Not a big one, but removing the swagger: "2.0" identifier--it will now just be openapi.
- Cookies - I'm not a big fan of this being introduced, but it makes sense, and I'm sure is usable for many API operators.
The OAI blog provides a five-part series covering the version 3.0 release. These ten areas are the highlights for me. I think they nailed it as far as what was needed, while also pushing into areas like linking and webhooks that I hadn't anticipated. I am looking forward to playing with converting some of my 2.0 specs to be 3.0 compliant--once I am a little more intimate with it, I can do better to estimate how long it will take for me to evolve my platform from 2.0 to 3.0.
I am impressed with what the OpenAPI Spec working group has gotten accomplished. I am optimistic about what is possible with OpenAPI Spec in 2017--something I'm going to be investing in heavily.