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.
Deprecation
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 striked out in the docs.
type: object properties: brightIdea: description: Some ideas don't stand the test of time. type: string deprecated: true
It’s liberating to take ownership over past mistakes. Using this feature may add years to your life.
Write-only Properties
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.
type: object properties: password: description: A secret password type: string writeOnly: true
Nullable
Let’s say you have a simple API, and here is a sample request:
"{" "name": "Adam", "favoriteColor": "green" "}"
But this request may also be valid.
"{" "name": "Adam", "favoriteColor": null "}"
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.
type: object properties: name: description: The person's name type: string favoriteColor: type: string nullable: true 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?