Three OpenAPI 3 Features Not to be Missed

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.

type: object
    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
    description: A secret password
    type: string
    writeOnly: true


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
    description: The person's name
    type: string
    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?

How API-First Design Helped Win a $22m Enterprise Deal

The background…

By the time ReDoc was released in 2015, I was more comfortable with the OpenAPI (fka Swagger) specification. We had a system to structure our API definitions into three folders: code_samples, definitions, and paths. I could quickly define a new API, and was getting comfortable doing so… At Rebilly, a great opportunity arose to work with a larger enterprise. However, they said it would be a lengthy integration process as they use a 3rd party ERP, and rely on the 3rd party for integrations. We waited. And waited.

I prepared an integration guide, specifically for them, mapping their terminology into ours, and preparing various sequences to outline the main use cases they would be implementing. After discussing the guide with our customer, it became clear that the already lengthy integration might never actually be completed.

Transition to API-Design First

We needed a different approach: a different API. It needed to be more familiar to the 3rd party, but would still allow us to deliver on our key promises. We decided to craft a partner-specific API. Instead of building the API first, we decided to co-design it with our partner.

Step 1. Shared Github Repo

And to do that, we used a private Github repository, with our familiar 3-folder structure.

Step 2. Setup CI to Build Docs

We hooked up Jenkins continuous integration server to build the ReDoc rendered API docs for both the working branches (we called these previews) and the mainline branch (our master). Then, we created an initial proposal for the API.

Step 3. Collaborate in the docs (not outside the docs)

Business analysts at our client and the 3rd party were able to read the rendered API Reference docs, and ask further questions. We answered their questions by adjusting the API definitions, and then sharing the new preview version of the API reference docs. We ended up with flowcharts, and free-formed documentation inside of our definition — not a typical definition. Ultimately, they became convinced and the tables were turned on us. Suddenly, they needed the API, as fast as possible.

Step 4. Build

Thankfully, by the time we began development, we knew we would be building something they could integrate more quickly — so we were confident in making that investment ourselves. Because we had elaborated our API Docs before we built our API, our team was also really clear on what they had to build, and it boosted the development speed.

Step 5. Profit

Since we were only getting paid once the API was in-use, this sped up the time to get cash. Our development finished quickly, and the integration was ultimately a success.

Using API Docs in API-Design First Approach Yields Better Results

API Docs played a big part in the API-First Design methodology, because many of the stakeholders were non-technical or just not familiar with Swagger at that time. Presenting visually appealing API draft docs, made Rebilly seem professional and competent. And it allowed for more participation in collaboration. The docs were easier to read. Looking back on that day, ReDoc helped Rebilly win a $22m enterprise deal.

Hello world, our mission is to perfect the API Developer Portal

ReDoc was born out of frustration with rendering my OpenAPI definitions for API reference docs.

Developer documentation is very important to a developer’s experience.

And that documentation extends beyond the API reference.

An API Developer Portal extends beyond mere documentation too.

Our mission is to perfect the API Developer Portal, one big factor of the developer experience. The other factors will likely be your API design, implementation, uptime, and speed.

Please comment or contact us to let us know about excellent and terrible experiences you’ve had with developer portals. There is plenty of learning to do from both ends of the spectrum.

To read or learn more, check out our article on Medium about API Docs.

Or stay tuned by requesting an invite.