A few weeks ago, we migrated three API definitions that I maintain and contribute to OpenAPI 3 from Swagger 2. It is relatively easy to transition from version 2 to 3. But just migrating the definition was one thing… being able to contribute to new API definitions was something else entirely. I found 3 new features immediately useful.
We all make bad decisions. Some of us are afraid to admit it. Sometimes we have to live with it. Okay, enough about me…
It’s quite easy to own up to mistakes in OpenAPI 3 because you can mark an operation or property as deprecated as simple as using the
deprecated attribute in your definition.
ReDoc visually renders it as a striked out in the docs.
description: Some ideas don't stand the test of time.
It’s liberating to take ownership over past mistakes. Using this feature may add years to your life.
I remember the first issue I opened regarding the swagger 2 spec was about write-only properties. My business case was about taking payment information securely, which means sensitive info only goes down a “one way street” to help merchants with PCI DSS compliance. It requires a write-only scenario, or returning something scrubbed in its place within the response.
To implement write-only in swagger 2 involved a lot of gymnastics (as can be seen in that issue). Now, it’s as simple as adding the
writeOnly attribute on any property.
description: A secret password
Let’s say you have a simple API, and here is a sample request:
But this request may also be valid.
The “favoriteColor” property could be a string or null.
In Swagger 2, there was a vendor extension. In OpenAPI 3, we can use the
nullable attribute to define that null is acceptable.
description: The person's name
description: The person's favorite color.
OpenAPI 3 > Swagger 2
OpenAPI 3 is an excellent and easy way to describe your API. If you have any choice (yes, we know you don’t always get to make that decision), choose OpenAPI 3. Then, if you decide to start deprecating a bunch of APIs, don’t blame it on me.
There are plenty of other exciting features in OpenAPI 3. These 3 are my favorites though, as they are so simple and practical.
What are your favorite additions to OpenAPI 3?